claude.ai 및 ChatGPT 커넥터

관리자 위치: System › Settings › API & AI agents (/agent/keys), Connected apps 탭. 동의 화면은 커넥터가 접근을 요청할 때 /agent/consent에서 열립니다 (메뉴에는 없습니다).

작동 내용

웹 AI 앱은 디스크에서 키를 읽을 수 없습니다. OAuth를 통해 연결됩니다. 패널의 MCP URL을 추가하면 앱이 로그인을 위해 자체 관리자로 리디렉션하고, 앱이 수행할 작업과 유지 기간을 선택하면 앱이 수명이 짧은 토큰을 받습니다. 키를 복사하거나 붙여넣지 않으며, 언제든지 앱을 차단할 수 있습니다.

claude.ai 커스텀 커넥터, ChatGPT 개발자 모드 커넥터, 그리고 동적 클라이언트 등록을 지원하는 기타 모든 MCP 클라이언트에 이를 사용하세요. 명령줄 도구도 동일한 흐름을 사용할 수 있지만, admin API key가 더 간단합니다.

요구 사항

항목	요구 사항
URL	https://cloud.example.com/mcp/admin, 인터넷에서 접근 가능해야 함 (벤더 서버가 연결됨).
리버스 프록시	패널 앞에 자체 프록시를 배치하는 경우, /mcp/admin, /oauth-admin/ 및 /.well-known/ 경로를 패널로 전달해야 합니다.
귀하	동의 화면에 사용하는 동일한 브라우저에서 NexCMP 관리자에 로그인한 상태여야 합니다.
클라이언트	Streamable HTTP를 통한 MCP, PKCE (S256)가 포함된 OAuth 2.1 및 동적 클라이언트 등록을 지원합니다.

연결

1. AI 앱에서 커스텀 MCP 커넥터를 추가하고 https://cloud.example.com/mcp/admin을(를) 붙여넣습니다. claude.ai에서는 커넥터 설정(커스텀 커넥터 추가)에 있고, ChatGPT에서는 개발자 모드(MCP 커넥터 추가, 인증 OAuth)에 있습니다.
2. 앱에서 Sign in(또는 "Connect")을 선택합니다. 브라우저에 NexCMP 관리자 동의 화면이 열립니다. 로그인되어 있지 않은 경우 먼저 로그인하면 화면이 계속 진행됩니다.
3. 카드를 읽어보세요: "Example AI app wants to manage this NexCMP admin" (요청하는 앱 이름) 및 다시 리디렉션될 주소가 표시됩니다.
4. 부여할 범위를 체크하세요. 앱이 요청한 항목은 미리 체크되어 있으며, 요청된 항목이 없으면 admin:read만 체크됩니다. Scopes를 참조하세요.
5. 연결 유지 기간을 선택하세요: 7, 30 또는 90일 (기본값 30).
6. Allow를 클릭합니다. 브라우저가 앱으로 돌아가며 이제 연결됩니다. 거부하려면 Deny를 클릭합니다.

::: important 키와 마찬가지로 범위 선택 작업을 수행하는 데 필요한 최소한의 집합을 부여하세요. 자금, 삭제 및 보안 작업은 여전히 미리원에서 중지되며 승인이 필요하지만, settings:write이(가) 포함된 연결은 브랜딩과 이메일을 변경할 수 있습니다. :::

관리 및 해제

System › Settings › API & AI agents › Connected apps를 엽니다. 테이블에는 연결한 모든 앱(애플리케이션, 범위, 연결 시점, 만료 시점, 마지막 사용 시점)이 나열됩니다.

앱을 차단하려면 Revoke를 클릭하고 확인합니다. 해당 토큰 즉시 작동이 중지되며, 앱은 다시 연결하려면 동의 과정을 다시 거쳐야 합니다.

작동 방식

단계	Detail
탐색	앱이 /.well-known/oauth-protected-resource/mcp/admin을(를) 읽고 이어 /.well-known/oauth-authorization-server/oauth-admin을(를) 읽습니다. 발급자는 https://cloud.example.com/oauth-admin입니다.
등록	앱이 자체적으로 등록합니다(POST /oauth-admin/register, RFC 7591). 퍼블릭 클라이언트만 지원됩니다(클라이언트 시크릿 없음). 리디렉션 주소는 https이거나 동일한 컴퓨터의 경우 http(루프백)여야 합니다.
인증	GET /oauth-admin/authorize(PKCE 메서드 S256 사용). resource 매개변수는 전송 시 이 패널의 /mcp/admin URL이어야 합니다. 요청은 10분 동안 유효하며 요청을 시작한 브라우저에 연결됩니다.
Consent	범위와 기간(위)을 선택합니다. 권한 부여 코드는 60초 동안 유효하며 한 번만 작동합니다.
Tokens	POST /oauth-admin/token은(는) 액세스 토큰(ak_o... 키, 1시간 동안 또는 연결이 종료될 때 중 빠른 시점까지 유효)과 리프레시 토큰(akr_...)을 반환합니다. 갱신할 때마다 새로운 리프레시 토큰이 반환되며 이전 토큰은 작동을 멈춥니다. 연결은 선택한 일수가 지나면 종료됩니다.
Revocation	연결된 앱의 Revoke 또는 앱에서 POST /oauth-admin/revoke 호출(RFC 7009).

액세스 토큰은 부여한 범위가 지정된 관리자 키처럼 작동합니다. 동일한 범위 규칙, 확인,율 제한 및 활동 로그가 적용됩니다. 호출 내역은 Activity 탭에 표시됩니다.

확인

1. 앱에서 "run system_health"(또는 "what tools do you have?")라고 질문합니다. 앱은 범위에서 허용하는 도구(the tool list)를 나열합니다.
2. Connected apps를 엽니다. Last used가 이동합니다.
3. Activity를 엽니다. 호출 내역이 앱 이름 및 mcp와(과) 함께 나열됩니다.

한도 및 참고 사항

• 1시간 후에 앱에서 로그인을 다시 요구하는 경우, 클라이언트가 토큰을 갱신하지 않을 때 정상적으로 발생하는 현상이므로 다시 연결하세요.
• 두 번 사용된 리프레시 토큰은 도난당한 것으로 간주되어 전체 연결이 취소됩니다. 앱에서 다시 연결하세요.
• 두 번 사용된 권한 부여 코드는 거부되며(invalid_grant) 해당 코드로 이미 발급된 토큰은 취소됩니다.
• OAuth 액세스는 범위 규칙이 허용하는 범위를 초과하지 않습니다. what a key can never do은(는) 연결된 앱에도 적용됩니다.
• 공급업체는 메뉴와 지원 기능을 변경합니다. 공급업체의 앱이 회원님의 요금제에서 커스텀 커넥터를 제공하지 않는 경우, 대신 데스크톱 또는 명령줄 클라이언트와 함께 admin API key를 사용하세요.

Troubleshooting

증상	원인	해결 방법
동의 화면에 "Wrong browser"가 표시됨	로그인한 브라우저가 아닌 다른 브라우저에서 요청이 시작됨	동일한 브라우저의 AI 앱에서 연결을 다시 시작하세요.
동의 화면에 요청이 만료되었거나 누락되었다고 표시됨	10분이 넘게 지났거나 링크가 두 번 열림	AI 앱에서 연결을 다시 시작하세요.
"Unknown client" 또는 "redirect address does not match" 페이지	앱 등록이 만료되었거나 등록되지 않은 리디렉션 주소를 사용함	앱에서 커넥터를 제거한 후 다시 추가하세요.
invalid_target	전송된 resource이(가) 이 패널의 /mcp/admin URL이 아님	Connect an AI 탭에 표시된 정확한 URL을 사용하세요.
invalid_request about PKCE	클라이언트가 code_challenge_method=S256을(를) 전송하지 않음	PKCE를 지원하는 OAuth 2.1 클라이언트를 사용하세요.
앱은 연결되지만 호출 시 insufficient_scope이(가) 반환됨	해당 스코프를 체크하지 않음	연결을 해제하고 스코프를 체크한 상태로 다시 연결하세요.
앱이 URL에 도달할 수 없음	DNS, TLS 또는 리버스 프록시가 /mcp/admin, /oauth-admin/ 또는 /.well-known/을(를) 차단함	프록시 규칙을 확인하세요.