mcp-use + Scalekit MCP Auth

mcp-use MCP 서버로, Scalekit OAuth 2.1로 인증합니다.

팀원이 하나의 서버 URL을 공유합니다. 각자가 로그인합니다. 도구는 공유 API 키가 아니라 자신의 신원(ctx.auth.user.id)을 봅니다.

이 예제는 @scalekit-sdk/node를 사용하지 않으며, Scalekit 클라이언트 ID나 시크릿도 필요하지 않습니다. 리소스 서버는 Scalekit JWKS로 JWT를 검증합니다.

쿡북 형식의 방법 가이드는 docs/v2/typescript/server/authentication/providers/scalekit.mdx에 있습니다. 이 README는 이 저장소를 위한 실행 매뉴얼입니다.

[!IMPORTANT] 자신의 Scalekit 환경을 사용하세요. 이 저장소에는 플레이스홀더만 포함되어 있습니다. .env는 절대 커밋하지 마세요.

제공되는 것

• /mcp에서 제공되는 Streamable HTTP MCP

• RFC 9728 보호 리소스 메타데이터를 가리키는 401 + WWW-Authenticate

• 인가 서버로서의 Scalekit(DCR 및 CIMD)

• whoami — 인증된 사용자, 스코프, 토큰 iss / aud

• greet — ctx.auth.user.id를 키로 사용하는 도구

Related MCP server: Access Self-Hosted MCP Server

클라이언트 로그인 방법

sequenceDiagram
  participant Client as MCP client
  participant Server as This server
  participant SK as Your Scalekit env

  Client->>Server: POST /mcp (no token)
  Server-->>Client: 401 + WWW-Authenticate
  Client->>Server: GET /.well-known/oauth-protected-resource/mcp
  Server-->>Client: authorization_servers = Scalekit resource issuer
  Client->>SK: Discover AS metadata, register via DCR or CIMD
  Client->>SK: User signs in and consents
  SK-->>Client: Access token (aud includes res_…)
  Client->>Server: POST /mcp Authorization: Bearer …
  Server-->>Client: Tool result scoped to ctx.auth.user.id

사전 요구 사항

• Node.js 22.22.2 이상

• Scalekit 계정(계정이 없다면 가입)

• 인증 방법 하나 이상 활성화(Google, GitHub, 비밀번호 없는 로그인 또는 엔터프라이즈 SSO)

1. Scalekit에 MCP 서버 등록

다음 값을 사용하여 MCP Auth 퀵스타트를 진행하세요.

1. Scalekit Dashboard를 열고 MCP 서버 → MCP 서버 추가를 선택합니다.

2. 이름을 지정합니다. 이 이름이 동의 화면에 표시됩니다.

3. 동적 클라이언트 등록과 **클라이언트 ID 메타데이터 문서(CIMD)**를 활성화합니다. Inspector, Claude, Cursor 같은 공용 클라이언트에는 이 중 하나 이상이 필요합니다. 둘 다 켜 두세요.

4. 고급 설정에서 서버 URL을 다음으로 설정하세요.

   http://localhost:3000/mcp

   끝에 슬래시를 붙이지 마세요. 설정하면 Scalekit에서 이 URL을 액세스 토큰 aud 클레임에 res_… ID와 함께 기록합니다. 비워 두면 aud는 res_…뿐이지만 이 예제는 여전히 검증합니다.

5. 저장하세요. 서버 페이지에서 다음을 복사하세요.

   • 환경 URL — https://<your-env>.scalekit.cloud

   • 리소스 ID — res_…

[!CAUTION] 나중에 DCR 또는 CIMD를 전환하면 MCP 클라이언트를 다시 연결하세요. Inspector 및 기타 클라이언트는 인가 서버 메타데이터를 캐시하지만 이 프로세스는 캐시하지 않습니다.

2. 이 저장소 구성

git clone git@github.com:scalekit-developers/scalekit-mcpuse-example.git
cd scalekit-mcpuse-example
npm install
cp .env.example .env

.env를 자신의 값으로 편집합니다. 이 저장소에는 샘플 자격 증명이 없습니다.

SCALEKIT_ENVIRONMENT_URL=https://your-env.scalekit.cloud
SCALEKIT_RESOURCE_ID=res_xxxxxxxx
MCP_URL=http://localhost:3000/mcp

SCALEKIT_CLIENT_ID 또는 SCALEKIT_CLIENT_SECRET은 없습니다. 리소스 서버는 Scalekit이 이미 발급한 토큰만 검증합니다.

3. 실행 및 로그인

npm run dev

1. Inspector를 엽니다.

2. http://localhost:3000/mcp에 연결합니다. 첫 번째 호출은 401을 반환하고 Inspector가 Scalekit 로그인을 시작합니다.

3. 브라우저에서 동의를 완료합니다.

4. **whoami**를 호출합니다.

usr_… ID, subjectType: "user", openid / profile 같은 스코프와 함께 다음이 표시되어야 합니다:

{
  "iss": "https://your-env.scalekit.cloud",
  "aud": ["http://localhost:3000/mcp", "res_xxxxxxxx"]
}

iss는 https://your-env.scalekit.cloud/resources/res_xxxxxxxx일 수도 있습니다. Scalekit이 발급자 값을 마이그레이션하는 동안 이 예제는 둘 다 허용합니다.

그런 다음 **greet**를 호출합니다. 인사말은 검증된 토큰의 ctx.auth.user.id를 사용합니다. 이것이 사용자별로 도구 데이터 범위를 지정하는 패턴입니다.

검증 작동 방식

oauth: oauthScalekitProvider({
  environmentUrl: process.env.SCALEKIT_ENVIRONMENT_URL!,
  resourceId: process.env.SCALEKIT_RESOURCE_ID!,
  resource: process.env.MCP_URL!,
}),

resourceId는 JWT aud(res_…)입니다. resource는 공개 MCP URL입니다. mcp-use는 resource를 RFC 9728 보호 리소스 메타데이터에 넣습니다. 이는 두 번째 audience 검사가 아닙니다.

resourceId는 서버별 보안 경계입니다. 동일한 Scalekit 환경의 다른 MCP 서버용으로 발급된 토큰은 반드시 실패해야 합니다.

인가는 도구 옆에 있어야 합니다:

async (_args, ctx) => {
  // ctx.auth.user.id is this caller — scope your data to it
  if (!ctx.auth.scopes.includes("todos:write")) {
    return { isError: true, content: [{ type: "text", text: "Missing scope" }] };
  }
};

oauth/scalekit.ts는 일급 mcp-use/oauth/scalekit 어댑터의 프로토타입입니다. 아직 npm에 게시되지 않았습니다.

프로젝트 구조

공개 URL 변경

서버를 공개하는 경우(터널, 배포, 사용자 지정 호스트):

1. Scalekit의 서버 URL을 해당 오리진 + /mcp로 설정합니다(끝 슬래시 없음).

2. MCP_URL을 동일한 문자열로 설정합니다.

3. 이 프로세스를 다시 시작합니다.

검증기는 변경되지 않습니다. resourceId는 계속 audience 검사로 남습니다.

문제 해결

Scalekit은 MCP 인증 문제 해결 가이드도 제공합니다.

보안

• 이 저장소에 클라이언트 시크릿, API 키 또는 개인 환경 URL을 넣지 마세요.

• .env는 gitignore 처리되어 있습니다. .env.example만 커밋하세요.

• 이 프로세스는 클라이언트 시크릿으로 Scalekit을 호출하지 않습니다. Bearer 토큰만 검증합니다.

• MCP_USE_OAUTH_DEBUG=1은 iss / aud / sub를 위해 JWT 페이로드를 디코딩합니다. 토큰은 출력하지 않습니다.

문서

• mcp-use 서버를 Scalekit으로 인증

• Scalekit MCP Auth 퀵스타트

• Scalekit MCP 개요

• mcp-use

• MCP 인가 사양