직접 작성한 코드에서 호출
이 페이지는 Claude나 Cursor 같은 AI 어시스턴트가 아니라, 직접 운영하는 스크립트, 백엔드 서비스, 에이전트에서 NameBeta 도구를 호출하려는 개발자를 위한 문서입니다.
모든 토큰은 사람의 로그인에서 시작됩니다
NameBeta에는 API 키도, 클라이언트 자격 증명 그랜트도 없습니다. MCP 서버가 받아들이는 액세스 토큰은 모두 권한 부여에 설명된 대로 NameBeta 사용자가 브라우저에서 로그인하고 동의 화면에서 클라이언트를 승인한 뒤에 발급된 것입니다. 사람 없이 실행되는 프로그램은 첫 토큰을 스스로 얻을 수 없으므로, 이 로그인은 사람이 한 번 직접 완료해야 합니다.
로그인을 마친 뒤에는 프로그램이 리프레시 토큰을 가지고 있으면 사람 없이도 계속 동작할 수 있습니다. 권한 부여 요청에 설명된 대로 offline_access를 prompt=consent와 함께 요청하고, 액세스 토큰이 만료될 때마다 리프레시 토큰으로 새 토큰을 받으면 됩니다.
저희가 직접 작성한 스크립트로 이 흐름을 엔드투엔드로 실행해 보지 않았으므로, 이 페이지에서는 절차만 안내하고 코드는 싣지 않았습니다. 테스트를 거친 예시가 추가되면 변경 내역에서 알려 드리겠습니다.
현재 사용할 수 있는 방법
이미 MCP 클라이언트인 에이전트 사용
직접 클라이언트를 만들기보다 NameBeta 도구를 쓸 수 있는 에이전트가 필요한 것이라면, 문서에서 안내하는 클라이언트 중 하나를 실행하세요. 이 클라이언트들은 로그인과 토큰 갱신을 스스로 처리합니다. Claude Code와 Codex는 터미널과 스크립트에서 실행할 수 있습니다.
OAuth 클라이언트 직접 작성
직접 작성한 코드에서 엔드포인트를 호출하려면 프로그램이 OAuth 클라이언트 역할을 해야 합니다.
- 직접 관리하는 HTTPS URL에 Client ID Metadata Document를 호스팅합니다. 이 URL이
client_id가 되며, 문서에는 클라이언트 이름과 리디렉션 URI를 적습니다. 다른 등록 단계가 없는 이유는 클라이언트 등록에서 설명합니다. 문서를 호스팅할 수 없다면 사전 등록된 클라이언트 ID를 요청하세요. - 호출을 요금제 할당량에서 차감할 NameBeta 사용자로 브라우저에서 PKCE를 사용하는 권한 부여 코드 흐름을 한 번 실행합니다.
resource=https://namebeta.com/api/mcp를 보내고, 리프레시 토큰을 받기 위해offline_access를prompt=consent와 함께 요청합니다. - 프로그램이 읽을 수 있는 곳에 리프레시 토큰을 저장하고, 현재 액세스 토큰이 만료되면 리프레시 토큰으로 새 액세스 토큰을 받습니다.
- 엔드포인트와 전송 방식에 설명된 대로
Authorization: Bearer <access token>을 붙여POST당 JSON-RPC 요청 하나씩 엔드포인트를 호출합니다.
공식 MCP SDK는 2단계와 4단계를 구현합니다. TypeScript SDK(@modelcontextprotocol/sdk, 1.30.0)는 권한 부여 서버가 Client ID Metadata Document를 지원하고 클라이언트의 OAuthClientProvider에 clientMetadataUrl이 설정되어 있으면 이를 사용합니다. 단, 문서 호스팅은 여전히 직접 해야 합니다.
모델 API에 토큰 전달
모델 API의 MCP 커넥터는 서버 호출을 대신해 주지만 로그인은 하지 않습니다. 앞 절의 방법으로 얻은 액세스 토큰을 전달하고, 토큰 갱신도 직접 처리해야 합니다.
| API | 토큰 전달 위치 | 공급업체 문서 |
|---|---|---|
| Claude API (Messages) | mcp_servers 항목의 authorization_token | MCP connector |
| OpenAI API (Responses) | mcp 도구의 authorization | MCP and Connectors |
Anthropic 문서에는 다음과 같이 적혀 있습니다. "API consumers are expected to handle the OAuth flow and obtain the access token prior to making the API call, and to refresh the token as needed."(API 사용자는 API를 호출하기 전에 OAuth 흐름을 처리해 액세스 토큰을 얻고, 필요에 따라 토큰을 갱신해야 합니다.) OpenAI 문서에는 다음과 같이 적혀 있습니다. "OAuth client registration and authorization must be handled separately by your application."(OAuth 클라이언트 등록과 권한 부여는 애플리케이션에서 별도로 처리해야 합니다.)
사용할 수 없는 방법
- 다른 클라이언트에서 복사한 토큰. 해당 클라이언트에 발급된 토큰이며 곧 만료됩니다. 직접 클라이언트를 만드세요.
- 동적 클라이언트 등록. NameBeta는 제공하지 않습니다. 클라이언트 등록을 참조하세요.