# MCP 接入指南

Arkme MCP Server 面向 MCP Host 和外部 Agent，通过标准 Streamable HTTP 暴露 Tool。Host 负责 MCP 协议交互，业务代码不直接拼装 JSON-RPC。

| 参数 | 值 |
| --- | --- |
| MCP Server URL | `https://openapi.jotmo.cc/mcp` |
| Transport | Stateless Streamable HTTP |
| 认证 Header | `Authorization: Bearer arkme_...` |

先在 [开发者控制台](/console) 创建个人 API Key，再把 Server URL 和认证 Header 配置到 MCP Host。Arkme 使用静态 Bearer API Key 认证，不发布 OAuth 发现文档；调用方必须支持为 Streamable HTTP 连接配置自定义 Header。

## 连接与发现

Arkme MCP Server 提供以下标准协议入口：

1. `server/discover` 获取支持的协议版本、Server Identity 和能力类别。Arkme 声明 `tools` 能力。
2. `tools/list` 获取当前 Tool 名称、描述、Input Schema 和 Output Schema。
3. `tools/call` 调用选定的 Tool。

## Tool 合同

Tool 名称、描述、Input Schema 和 Output Schema 以运行时 `tools/list` 响应为机器合同。

| Tool | 输入 | 结构化输出 |
| --- | --- | --- |
| `get_current_user_profile` | 空对象 | `nickname`、`jotmo_id`、`created_at` |
| `get_current_user_account_bindings` | 空对象 | `items`，只包含登录方式及是否绑定 |

两个 Tool 都读取 API Key 所属用户，不接受 `user_id`。Tool 成功时返回 `structuredContent`，并同时提供等价 JSON 文本；Agent 应优先读取 `structuredContent`。

## 协议边界

- Server 只声明 `tools`，不提供 MCP resources、prompts、sampling 或 tasks。
- Server 无状态，不分配 `MCP-Session-Id`。
- 不要把 `/mcp` 当作 REST API，也不要按 Arkme REST 响应包解析 MCP 结果。
- 不要用 REST OpenAPI 文件生成 MCP Client；使用支持 Streamable HTTP 和自定义 Header 的 MCP SDK 或 Host。

## 错误处理

- `401`：API Key 缺失、无效、已删除，或所属账号不可用。
- `400`：JSON-RPC、协议版本、Content-Type 或 `Accept` 不合法。
- `405`：对无状态 Server 使用了不支持的会话操作。
- `413/415`：请求体过大或 Content-Type 不正确。
- `429`：调用过快。
- `502/503`：账号服务、认证存储或限流依赖暂时不可用。

Tool 已进入 JSON-RPC 执行后，业务失败通过 `CallToolResult.isError=true` 返回，不使用 REST 的 `code/message/data` 响应包。