crank/docs/mcp-interface.md

MCP Interface

Crank Community публикует REST operations как MCP tools поверх Streamable HTTP.

Transport

MCP server запускается отдельным приложением mcp-server.

Поддерживается:

• MCP Streamable HTTP;
• JSON-RPC requests через POST;
• optional server-to-client stream через GET;
• explicit session close через DELETE.

stdio не входит в Community deployment.

Endpoint model

Canonical endpoint:

/mcp/v1/{workspace_slug}/{agent_slug}

Endpoint определяет:

• workspace;
• published agent;
• curated tool catalog агента;
• labels для logs и usage.

Authentication

Community использует static agent API keys.

Правила:

• каждый published agent может иметь собственные API keys;
• key принадлежит одному workspace и одному agent;
• mcp-server показывает только tools, привязанные к этому agent;
• unsupported token issuance modes отклоняются.

Tool catalog

Одна published REST operation становится одним MCP tool.

Tool definition строится из:

• operation name или binding-level tool name;
• tool title и description;
• input schema;
• published operation version.

Draft operations никогда не публикуются через MCP.

Supported methods

MCP methods:

• initialize
• notifications/initialized
• ping
• tools/list
• tools/call

Transport endpoints:

• POST /mcp/v1/{workspace_slug}/{agent_slug}
• GET /mcp/v1/{workspace_slug}/{agent_slug}
• DELETE /mcp/v1/{workspace_slug}/{agent_slug}

tools/list

1. Client authenticates через agent API key.
2. mcp-server resolves workspace и agent из path.
3. Server loads published agent catalog.
4. Server returns only tools bound to that agent.

tools/call

1. Client вызывает tool.
2. mcp-server валидирует input по tool schema.
3. Runtime maps MCP input в REST request.
4. REST adapter вызывает upstream API.
5. Runtime maps REST response в tool output.
6. mcp-server возвращает normalized result.

Refresh

Published catalog refresh управляется CRANK_MCP_REFRESH_MS.

После публикации operation или agent mcp-server подхватывает новый catalog без restart.

Error categories

MCP responses различают:

• authentication errors;
• missing workspace или agent;
• missing tool;
• schema validation errors;
• mapping errors;
• upstream REST errors;
• internal runtime errors.