Sume MCP 서버 OAuth 플로: 디스커버리·동의·PKCE·스코프

Sume 호스팅 MCP 서버는 자체 OAuth 인가 서버입니다. 토큰 없이 https://mcp.sume.com/mcp에 요청하면 protected-resource 메타데이터를 가리키는 401을 받고, 사용자는 mcp.sume.com의 자사 동의 페이지에서 로그인해 권한을 고르며, 클라이언트는 인가 코드와 PKCE verifier를 스코프가 mcp:read, 또는 mcp:read와 mcp:write인 bearer 토큰으로 교환합니다.

각 단계는 MCP OAuth와 API 키와 MCP 빠른 시작을 바탕으로 하며, 2026-09-26에 확인했습니다. 파라미터, 오류 코드, 토큰 수명은 그날 프로덕션이 제공한 메타데이터와 그 뒤의 서버 코드에서 가져왔으므로 현재 동작을 설명합니다. Sume의 기초 페이지는 CLI와 호스팅 MCP가 여전히 동작하지만 현재 주 연동 경로는 아니라고 설명합니다. 백엔드는 HTTP로 Format API나 Developer API를 호출합니다. 클라이언트별 설정 명령어는 Claude Code·Cursor·Codex를 호스팅 MCP로 Sume에 연결에 있습니다.

Sume MCP OAuth 플로는 어떤 단계로 진행되나요?

순서는 다음과 같습니다.

• 클라이언트가 토큰 없이 https://mcp.sume.com/mcp를 호출하면, protected-resource 메타데이터 URL과 scope mcp:read를 담은 WWW-Authenticate 헤더와 함께 401을 받습니다.
• 메타데이터의 authorization_servers는 www.sume.com이나 app.sume.com이 아니라 MCP origin입니다.
• 클라이언트가 사용자를 https://mcp.sume.com/oauth/authorize로 보내면, 이 주소는 같은 호스트의 자사 동의 페이지 GET /oauth/consent로 리다이렉트합니다. 이미 로그인한 사용자도 동의 화면을 거칩니다.
• 동의 화면의 Permissions에서 Read는 켜진 채 고정되고, Write 토글은 기본적으로 꺼져 있습니다. Continue를 누르면 선택이 POST /oauth/consent/decision으로 전송되고, 브라우저가 코드를 가지고 클라이언트로 돌아갑니다.
• 클라이언트가 코드와 PKCE verifier를 액세스 토큰으로 교환합니다.
• 클라이언트가 그 bearer 토큰으로 https://mcp.sume.com/mcp를 호출합니다.

디스커버리 메타데이터는 어디에 있고, 무엇을 알려 주나요?

서버를 설명하는 공개 문서는 두 개입니다. 리소스 audience는 https://mcp.sume.com/mcp입니다. www.sume.com은 지원 중단된(deprecated) 인가 서버 표면으로 남아 있지만 메타데이터는 더 이상 이를 알리지 않으며, 인터랙티브 클라이언트를 MCP OAuth 때문에 app.sume.com으로 보내서는 안 됩니다.

https://mcp.sume.com/.well-known/oauth-protected-resource/mcp
https://mcp.sume.com/.well-known/oauth-authorization-server

클라이언트는 authorize와 토큰 엔드포인트에 무엇을 보내나요?

authorize 리다이렉트에는 response_type=code, client_id, redirect_uri, code_challenge, code_challenge_method=S256, state, resource가 담기며, scope는 선택입니다. S256만 받습니다. 리다이렉트 URI는 https, localhost나 127.0.0.1의 http, 또는 Cursor 전용 cursor:// 콜백이어야 합니다.

토큰 요청은 grant_type=authorization_code, code, client_id, redirect_uri, code_verifier를 보내며, resource의 기본값은 https://mcp.sume.com/mcp입니다. 클라이언트, 리다이렉트 URI, 리소스와 맞지 않는 코드나, 해시가 챌린지와 일치하지 않는 verifier는 invalid_grant를 받습니다. 그 밖의 grant_type은 unsupported_grant_type을 받습니다.

동적 클라이언트 등록은 redirect_uris(최대 10개)를 /oauth/register로 POST합니다. token_endpoint_auth_method는 none이어야 합니다. 클라이언트 시크릿이 없는 공개 클라이언트이기 때문입니다.

Sume MCP 토큰에는 어떤 스코프가 담길 수 있나요?

두 가지입니다. 필수인 mcp:read, 그리고 항상 읽기를 포함하는 mcp:write입니다. 세션마다 무엇을 호출할 수 있는지는 Claude Code·Cursor·Codex를 호스팅 MCP로 Sume에 연결에 있습니다. authorize 요청의 scope에 그 밖의 값을 넣으면 mcp:paid를 포함해 모두 invalid_scope로 실패합니다.

결정은 클라이언트가 아니라 사용자가 합니다. 클라이언트가 mcp:write를 요청했더라도, 부여되는 스코프는 동의 페이지의 Write 토글에서 정해집니다. 쓰기 없이 발급된 토큰은 쓰기·유료 도구에서 insufficient_scope를 받으며, 해결 방법은 Sume MCP 문제 해결에 있습니다.

코드와 토큰은 얼마 동안 유효한가요?

현재 서버에서는 둘 다 수명이 짧고, 리프레시가 없습니다.

• 인가 코드는 10분 동안 유효하며 한 번만 쓸 수 있습니다. 같은 코드를 두 번째로 교환하면 invalid_grant를 받습니다.
• 액세스 토큰은 한 시간 동안 유효합니다. 토큰 응답에는 access_token, token_type Bearer, expires_in 3600, scope가 담기며, 리프레시 토큰은 없습니다.
• 서버는 리프레시 토큰을 발급하지 않습니다. 클라이언트가 등록 시 grant_types에 refresh_token을 넣을 수는 있지만, 서버는 이를 무시합니다.
• 만료되거나 폐기된 토큰은 토큰이 없을 때와 같은 401 챌린지를 받으므로, 클라이언트는 인가 플로를 다시 실행합니다.
• /oauth/revoke는 클라이언트 인증 없이 토큰을 폐기합니다.

세션은 어떻게 확인하고, 토큰은 어떻게 안전하게 지키나요?

mcp_health를 호출하세요. OAuth에서는 authenticated.auth_source가 mcp_oauth이며, 현재 자격 증명 블록에는 type oauth_access_token, client_id, 부여된 scopes가 나옵니다.

MCP OAuth 토큰은 Sume API 키가 아니며, 저장과 공유 규칙은 AI 에이전트의 안전한 자동화에 있습니다. 플로 자체에 속하는 점은 두 가지입니다. sume login은 호스팅 MCP 토큰을 중개하지 않으며, OAuth를 지원하지 않는 자동화는 대신 API 키를 Authorization: Bearer $SUME_API_KEY나 x-api-key 중 하나로 보냅니다. 둘 다 보내지는 않습니다.