> ## Documentation Index > Fetch the complete documentation index at: https://docs.onecortex.io/llms.txt > Use this file to discover all available pages before exploring further. # Call an agent as an MCP tool > The agent as an MCP server with one tool, `ask_` and the agent's slug with hyphens as underscores. MCP 2026-07-28, and the 2025-11-25 `initialize` handshake. Stateless: every request is answered on its own. `server/discover` and `tools/list` describe the tool, `tools/call` runs the agent with its `prompt`, `session_id` and `resume` arguments, and returns the reply as one text block with the session in `structuredContent`. A client that sends a progress token gets progress notifications on a stream while the run works. A run that fails is a tool result with `isError: true`. A paused run asks a client that can elicit for a form and continues on its retry; any other client gets the question as text and answers with `resume`. An API key works here, and so does an access token from signing in: a call with no credential answers `401` with a `WWW-Authenticate` header naming the sign in metadata. A refusal of the call itself keeps its HTTP status with a JSON-RPC error body. See [MCP](/call/mcp). ## OpenAPI ````yaml /openapi.yaml post /v1/agents/{agentId}/mcp openapi: 3.1.0 info: title: Onecortex API version: '1' description: >- Call a deployed agent over invoke, AG-UI or A2A, and read its public A2A Agent Card. This is the whole public API. servers: - url: https://api.onecortex.io security: - apiKey: [] paths: /v1/agents/{agentId}/mcp: post: summary: Call an agent as an MCP tool description: > The agent as an MCP server with one tool, `ask_` and the agent's slug with hyphens as underscores. MCP 2026-07-28, and the 2025-11-25 `initialize` handshake. Stateless: every request is answered on its own. `server/discover` and `tools/list` describe the tool, `tools/call` runs the agent with its `prompt`, `session_id` and `resume` arguments, and returns the reply as one text block with the session in `structuredContent`. A client that sends a progress token gets progress notifications on a stream while the run works. A run that fails is a tool result with `isError: true`. A paused run asks a client that can elicit for a form and continues on its retry; any other client gets the question as text and answers with `resume`. An API key works here, and so does an access token from signing in: a call with no credential answers `401` with a `WWW-Authenticate` header naming the sign in metadata. A refusal of the call itself keeps its HTTP status with a JSON-RPC error body. See [MCP](/call/mcp). operationId: callAgentMcp parameters: - $ref: '#/components/parameters/AgentId' - name: MCP-Protocol-Version in: header required: true description: >- `2026-07-28`, equal to the version in the request's `_meta`. A 2025-11-25 client sends it after `initialize`. schema: type: string example: '2026-07-28' - name: Mcp-Method in: header required: true description: The JSON-RPC method, as in the body. schema: type: string example: tools/call - name: Mcp-Name in: header required: false description: The tool's name, on `tools/call`. schema: type: string example: ask_echo requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/JsonRpcRequest' example: jsonrpc: '2.0' id: 1 method: tools/call params: name: ask_echo arguments: prompt: hello _meta: io.modelcontextprotocol/protocolVersion: '2026-07-28' io.modelcontextprotocol/clientCapabilities: {} responses: '200': description: >- A JSON-RPC response, or a stream of progress notifications ending with it. content: application/json: schema: $ref: '#/components/schemas/JsonRpcResponse' example: jsonrpc: '2.0' id: 1 result: content: - type: text text: 'You said: hello' structuredContent: sessionId: 01K0000000000000000000000 resultType: complete text/event-stream: schema: type: string description: > Progress notifications, then the result, one `event: message` frame each. ```text event: message data: {"jsonrpc":"2.0","method":"notifications/progress","params":{"progressToken":"p1","progress":1,"message":"Calling tool word_count"}} event: message data: {"result":{"content":[{"type":"text","text":"You said: hello"}],"structuredContent":{"sessionId":"01K..."},"resultType":"complete"},"jsonrpc":"2.0","id":1} ``` '400': description: >- A protocol version this server does not speak, or headers that do not match the body. content: application/json: schema: $ref: '#/components/schemas/JsonRpcResponse' example: jsonrpc: '2.0' id: 1 error: code: -32022 message: 'Unsupported protocol version: 2024-01-01' data: supported: - '2026-07-28' requested: '2024-01-01' '401': description: The credential is missing, unknown, revoked or expired. headers: WWW-Authenticate: description: Where a client learns how to sign in. schema: type: string example: >- Bearer resource_metadata="https://api.onecortex.io/.well-known/oauth-protected-resource/v1/agents/agt_01K0000000000000000000000/mcp", scope="agent:invoke" content: application/json: schema: $ref: '#/components/schemas/JsonRpcResponse' example: jsonrpc: '2.0' id: null error: code: -32600 message: A valid Onecortex API key is required. '404': description: >- No such agent in your organization, or the credential is for another agent. content: application/json: schema: $ref: '#/components/schemas/JsonRpcResponse' example: jsonrpc: '2.0' id: null error: code: -32600 message: That agent does not exist. '429': description: Over a rate limit. Wait for `Retry-After`, then retry. headers: Retry-After: description: Whole seconds to wait. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/JsonRpcResponse' x-codeSamples: - lang: typescript label: TypeScript source: > import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client' const url = new URL('https://api.onecortex.io/v1/agents/agt_.../mcp') const client = new Client({ name: 'my-app', version: '1.0.0' }, { versionNegotiation: { mode: 'auto' } }) await client.connect(new StreamableHTTPClientTransport(url, { requestInit: { headers: { Authorization: `Bearer ${process.env.ONECORTEX_API_KEY}` } }, })) const { tools } = await client.listTools() const result = await client.callTool({ name: tools[0].name, arguments: { prompt: 'hello' } }) console.log(result.content) - lang: bash label: curl source: | curl https://api.onecortex.io/v1/agents/agt_.../mcp \ -H "Authorization: Bearer $ONECORTEX_API_KEY" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "MCP-Protocol-Version: 2026-07-28" \ -H "Mcp-Method: tools/call" \ -H "Mcp-Name: ask_echo" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ask_echo","arguments":{"prompt":"hello"},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}' components: parameters: AgentId: name: agentId in: path required: true description: The agent's ID, from its page in the dashboard. schema: type: string example: agt_01K0000000000000000000000 schemas: JsonRpcRequest: type: object required: - jsonrpc - method properties: jsonrpc: const: '2.0' id: oneOf: - type: string - type: integer method: type: string example: SendMessage params: type: object additionalProperties: true JsonRpcResponse: type: object required: - jsonrpc properties: jsonrpc: const: '2.0' id: oneOf: - type: string - type: integer - type: 'null' result: type: object additionalProperties: true description: For SendMessage on 1.0, an object holding `task`. error: type: object properties: code: type: integer description: >- -32001 task not found, -32002 not cancelable, -32004 unsupported, -32005 content type not supported, -32009 version not supported, -32600, -32601, -32602, -32603. message: type: string securitySchemes: apiKey: type: http scheme: bearer description: >- An Onecortex API key, `oc_live_...`, from API keys in the dashboard, or an access token, `oc_oat_...`, that an app received when a person allowed it to use one agent. ````