# MCP

> Kanorio의 원격 MCP 서버를 통해 Claude, ChatGPT, Cursor 등의 어시스턴트를 Management API에 연결하십시오.

> Markdown version of https://kanorio.com/ko/developers/mcp. Append `.md` to any developer docs URL for this format. Index: https://kanorio.com/llms.txt · MCP: https://app.kanorio.com/api/mcp
>
> Translated from the English original: https://kanorio.com/en/developers/mcp.md

Model Context Protocol 서버는 AI 어시스턴트를 위한 Management API입니다. 모든 작업은 도구로 제공되며, 도구 이름은 [Management API 참조](https://kanorio.com/en/developers/management-api)의 `operationId`와 일치합니다(예: `posts_create`, `site_publish`). 권한, 오류, 속도 제한 및 초안의 동작은 REST API와 동일합니다.

|  |  |
|---|---|
| 서버 URL | `https://app.kanorio.com/api/mcp` |
| 전송 방식 | 스트리밍 HTTP |
| 인증 | OAuth 2.1 또는 Bearer 방식의 개인 액세스 토큰이나 서비스 계정 토큰 |
| 레지스트리 이름 | `com.kanorio/kanorio` |

## 커넥터 지원 어시스턴트

Claude, ChatGPT 및 내장 커넥터를 사용하는 기타 어시스턴트는 OAuth를 사용하므로 토큰을 직접 관리할 필요가 없습니다.

1. 어시스턴트의 커넥터 설정에서 서버 URL `https://app.kanorio.com/api/mcp`을 사용하여 사용자 지정 커넥터를 추가합니다. URL을 채팅창에 붙여넣지 마십시오.
2. 어시스턴트가 동의 페이지를 열면 Kanorio에 로그인하여 사이트와 권한을 선택하고 승인합니다.

어시스턴트는 `https://app.kanorio.com/.well-known/oauth-protected-resource`를 통해 나머지 정보를 자동으로 검색합니다. Kanorio는 동적 클라이언트 등록 및 클라이언트 ID 메타데이터 문서를 지원합니다. 승인된 앱은 계정 설정에서 언제든지 검토하고 취소할 수 있습니다.

## 키를 사용하는 코딩 어시스턴트

Cursor, Claude Code, Codex, Gemini CLI, Windsurf, VS Code는 개인 액세스 토큰을 사용합니다. [계정 설정 › API 액세스](https://app.kanorio.com/account/api-access)에서 토큰을 생성하십시오. 도구를 선택하면 토큰이 입력된 설정 정보가 Kanorio에 표시됩니다.

**Cursor** (`.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "kanorio": {
      "url": "https://app.kanorio.com/api/mcp",
      "headers": { "Authorization": "Bearer knr_pat_..." }
    }
  }
}
```

**Claude Code:**

```bash
claude mcp add --transport http kanorio https://app.kanorio.com/api/mcp --header "Authorization: Bearer knr_pat_..."
```

**VS Code** (`.vscode/mcp.json`):

```json
{
  "servers": {
    "kanorio": {
      "type": "http",
      "url": "https://app.kanorio.com/api/mcp",
      "headers": { "Authorization": "Bearer knr_pat_..." }
    }
  }
}
```

**Codex** (`~/.codex/config.toml`):

```toml
[mcp_servers.kanorio]
url = "https://app.kanorio.com/api/mcp"
http_headers = { "Authorization" = "Bearer knr_pat_..." }
```

토큰이 포함된 파일은 버전 관리 시스템에 포함하지 마십시오.

## 도구의 동작 방식

- **토큰 권한 내 작동:** `tools/list`는 토큰 권한 밖의 도구를 숨깁니다. `auth_whoami`를 호출하여 토큰 권한과 숨겨진 기능을 확인할 수 있습니다.
- **게시 전까지 초안 유지:** 콘텐츠 작성 작업은 `site_publish`, `posts_publish` 등의 게시 도구가 실행되기 전까지 초안 상태로 유지됩니다.
- **구조화된 결과:** 각 도구는 작업의 응답 스키마와 일치하는 구조화된 콘텐츠를 반환합니다. 목록은 [페이지네이션 엔벨로프](https://kanorio.com/ko/developers/basics/pagination)를 사용합니다.
- **오류:** 호출 실패 시 `isError`와 함께 [오류 엔벨로프](https://kanorio.com/ko/developers/basics/errors)가 반환됩니다. `FORBIDDEN`, 플랜 및 모드 오류는 버그가 아닌 제한 사항이며, `details`에 사용자가 수정해야 할 내용이 명시되어 있습니다.
- **멱등성:** 멱등성을 지원하는 생성 작업 도구는 `idempotencyKey` 인수를 사용합니다. [멱등성](https://kanorio.com/ko/developers/basics/idempotency)을 참조하십시오.
- **지원 중단:** 지원이 중단된 도구의 설명은 `[Deprecated, removed after …; use …]`로 시작합니다.

## 서버 버전

서버는 시맨틱 버전을 따르며, `serverInfo.version` 및 `https://app.kanorio.com/.well-known/mcp/server.json`에서 확인할 수 있습니다. [변경 로그](https://kanorio.com/en/developers/changelog)에 각 버전의 변경 사항이 기록됩니다. 메이저 버전 업데이트 시 기존 도구의 동작이 변경될 수 있으므로, 도구 스키마를 캐싱하는 클라이언트는 이를 새로 고쳐야 합니다.