# 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:

```text
/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.