문서 · MCP
MCP 클라이언트 연결
Cainer는 원격 MCP 서버(/mcp)를 제공합니다. 클라이언트는 OAuth로 연결하고 도구 목록을 발견해 호출합니다. 승인이 필요한 호출은 게이트에서 멈춥니다.
준비
선행 조건
- 워크스페이스와 에이전트가 있고, 운영자(또는 오너)가 그 에이전트에 MCP 연결 경로를 결속해 두어야 합니다. OAuth 동의 화면에서 선택할 경로가 이것입니다.
- 클라이언트가 원격 MCP(Streamable HTTP)와 OAuth + PKCE를 지원해야 합니다. 정적 API 키만 넣는 클라이언트는 MCP 대신 HTTP 에이전트 경로를 사용합니다.
- 서버 주소: 배포마다 다릅니다. 현재 배포의
/mcp주소를 사용하세요(운영 기본:https://cainer.vercel.app/mcp).
단계
연결하고 첫 호출까지
- 1
서버 추가
클라이언트의 원격 MCP 서버 추가 화면에
…/mcp를 넣습니다. 인증 방식은 OAuth를 고릅니다. - 2
동의 화면에서 경로 선택
Cainer 로그인 후, 이 클라이언트가 사용할 에이전트 경로를 고르고 승인합니다. 승인 결과는 감사 기록에 남습니다.
- 3
도구 발견
클라이언트가
initialize→tools/list를 호출합니다. 아래 도구 표가 그 결과입니다. - 4
첫 호출 확인
list_agents처럼 읽기 도구로 확인하세요. 쓰기 도구는 정책에 따라 승인이 필요할 수 있습니다.
인증
OAuth 세부
- 메타데이터:
/.well-known/oauth-protected-resource(RFC 9728),/.well-known/oauth-authorization-server(RFC 8414) - 지원 버전:
2026-07-28(최신·MCP Events 포함)2025-11-252025-06-182025-03-26
2025-11-25로 협상합니다. - 스코프는
mcp:call하나입니다. 401/403 응답에는WWW-Authenticate: Bearer resource_metadata="…", scope="mcp:call"가 붙습니다. - access token 수명은 1시간이고
refresh_token으로 회전합니다. 연결을 철회하면 refresh도 즉시 무효입니다. - loopback redirect(
http://127.0.0.1:<port>)는 포트를 무시하고 경로만 대조합니다.
도구
호출 가능한 도구
| 도구 | 설명 | 분류 |
|---|---|---|
list_agents | List the authenticated agent and its connections. | 읽기 |
request_approval | Request human approval before a sensitive tool action. | 쓰기 |
check_approval | Check the status of an approval request. | 읽기 |
log_activity | Record an agent activity message in the central log (self-push). | 쓰기 |
report_cost | Report usage/cost for the current agent (marked as an estimate). | 쓰기 |
get_context | Get the agent context: profile, connection, recent sessions. | 읽기 |
messenger.list_inbox | List open messenger tasks assigned to the authenticated agent (pull channel). | 읽기 |
messenger.claim | Claim an assigned messenger task (lease TTL applies). | 쓰기 |
messenger.post_reply | Post the reply for a claimed/running task; binds the correlation id and the thread. | 쓰기 |
messenger.update_task | Advance a claimed task: start it, or fail it with a reason. | 쓰기 |
messenger.delegate | Delegate work to another owner-selected bot route as a new relay task on the same thread (bounded hop; target must have an active delivery route). | 쓰기 |
workproduct.github_issue | Create a GitHub issue from a thread message through the connected GitHub integration. Fails closed (409) when no integration is connected. | 쓰기 |
workproduct.notion_page | Create a Notion page from a thread message under the connected Notion parent page. Fails closed (409) when no integration is connected. | 쓰기 |
문제 해결
자주 만나는 오류
- 연결이 매시간 끊깁니다 — refresh를 지원하지 않는 클라이언트입니다. 지원하는 클라이언트로 바꾸거나 재연결하세요.
- 동의 화면에 고를 경로가 없습니다 — 이 워크스페이스에 MCP 연결이 결속된 에이전트가 없습니다. 에이전트 화면에서 연결을 먼저 준비하세요.
- 403 (scope) — 토큰에
mcp:call이 없습니다. 새로 동의해 발급받으세요. - 401 (revoked) — 연결이 철회됐거나 만료됐습니다. 새로 연결해야 합니다.
- 버전 오류로 세션이 끊깁니다 — 서버는 요청 버전을 그대로 응답합니다. 클라이언트가 지원하지 않는 값을 보내는지 확인하세요.
상태
MCP 경로의 검증 상태
| 클라이언트 | 전송 | 자격 | 상태 | 다음 단계 |
|---|---|---|---|---|
| ChatGPT 커스텀 커넥터 (도구 호출) 대화 중 도구 목록을 발견하고 작업 조회·회신 도구를 직접 호출합니다. |
MCP (Streamable HTTP) | OAuth + PKCE | 실연결 검증 | — |
| ChatGPT dots — MCP Events push dots가 Cainer에 이벤트 구독을 걸고, 새 작업을 webhook으로 받아 스스로 실행합니다. |
MCP Events | OAuth + PKCE | 계약(목업) 검증 | provider가 실제로 events/subscribe를 호출하고 challenge를 통과한 감사 기록 구독 이벤트가 dot 실행과 같은 스레드 회신으로 이어지는 실측 |
| grok.com 커넥터 Grok 커넥터에 Cainer MCP 서버를 등록해 도구를 호출합니다. |
MCP (Streamable HTTP) | OAuth + PKCE | 구현됨·실검증 전 | oracle 절차로 커넥터 재인증(OAuth token exchange) 성공 grok.com에서 발생한 도구 호출의 감사 기록 |
| Grok Bot (URL + 헤더) Grok Bot이 Cainer MCP URL과 Bearer 헤더로 도구를 호출합니다. |
MCP (Streamable HTTP) | 에이전트 토큰 | 구현됨·실검증 전 | hosted 실행에서 남은 nonce 행 확인 |
| Claude (claude.ai / Desktop) 커스텀 커넥터 Claude에 Cainer MCP 서버를 추가해 도구를 호출합니다. |
MCP (Streamable HTTP) | OAuth + PKCE | 예정 | Cainer 계정이 아닌 일반 MCP 클라이언트용 provider 바인딩 실제 DCR + 도구 호출 + 1시간 후 refresh 실측 |
| Claude Code `claude mcp add`로 Cainer를 추가해 도구를 호출합니다. |
MCP (Streamable HTTP) | OAuth + PKCE | 예정 | 일반 MCP 클라이언트 바인딩 loopback 임의 포트 콜백 수용(구현됨) 실측 |
| Cursor Cursor MCP 설정에 Cainer를 추가해 도구를 호출합니다. |
MCP (Streamable HTTP) | OAuth + PKCE | 예정 | 일반 MCP 클라이언트 바인딩 OAuth + 도구 호출 실측 |
| VS Code (GitHub Copilot) VS Code MCP 설정으로 Cainer 도구를 호출합니다. |
MCP (Streamable HTTP) | OAuth + PKCE | 예정 | 일반 MCP 클라이언트 바인딩 도구 호출 실측 |
| Codex CLI `codex mcp`로 Cainer를 등록해 도구를 호출합니다. |
MCP (Streamable HTTP) | OAuth + PKCE | 예정 | 일반 MCP 클라이언트 바인딩 쓰기 도구 확인 프롬프트 실측 |
| Gemini CLI 원격 MCP 서버로 Cainer를 추가합니다. |
MCP (Streamable HTTP) | OAuth + PKCE | 미지원 | provider 바인딩 도입 SDK 1.x 버전 협상 실측 |
| Muse Muse 에이전트를 Cainer 경로에 붙입니다. |
MCP (Streamable HTTP) | OAuth + PKCE | 미지원 | Muse 지역 지원·계정 접근 자동 소비 계약 확인 |
- 실연결 검증 1개
- 계약(목업) 검증 4개
- 구현됨·실검증 전 2개
- 예정 5개
- 미지원 2개
상태는 증거로만 올라갑니다. 「실연결 검증」은 실제 클라이언트와의 왕복 기록이 있는 경우, 「계약(목업) 검증」은 loopback 계약 테스트만 있는 경우, 「구현됨·실검증 전」은 코드 경로만 있는 경우입니다.