# Invoke MCP Tools

`POST /mcp` · Core · MCP

The project's inbound MCP endpoint: Streamable HTTP, one JSON-RPC 2.0 request per POST. It serves `tools/list` and `tools/call`, where a tool is a project function or a tool on one of the project's registered MCP servers, as named when the token was minted.

It accepts only a token from Create MCP Token; a personal access token or an ordinary session token is refused with 403. A missing or invalid token answers 401 with a `WWW-Authenticate` header pointing at the discovery document.

A `tools/call` runs under the minting operator's live role, so the token never grants more than that operator holds. Authentication failures are HTTP errors; the outcome of a dispatched call is in the JSON-RPC body with HTTP 200.

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `projectSlug` | path | yes | The project's slug: the path segment after `@`. It is unique within the org. Example: `"storefront"`. |

## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `jsonrpc` | enum ("2.0") | yes | Always `2.0`. |
| `id` | object | no | A value the caller chooses, echoed in the reply. |
| _one of_ | | |  |
| _or_ | | |  |
| _or_ | | |  |
| `method` | string | yes | The JSON-RPC method: `tools/list` or `tools/call`. Any other method gets error -32601. |
| `params` | object | no | The method's parameters. For `tools/list`, an optional `cursor`. For `tools/call`, `name` (the tool's name, as `tools/list` shows it) and optional `arguments` (an object). The tool `get_invocation` takes `arguments.invocationId`, and `get_call` takes `arguments.callId`. |

## Responses

- **200**: The JSON-RPC reply. The HTTP status is 200 for any dispatch or execution outcome; a missing, invalid or revoked token is refused before JSON-RPC with 401 or 403.

| Field | Type | Required | Description |
|---|---|---|---|
| _one of_ | | |  |
| `jsonrpc` | enum ("2.0") | yes | Always `2.0`. |
| `id` | object | no | The request's id, echoed back. Omitted when the request had none. |
| _one of_ | | |  |
| _or_ | | |  |
| _or_ | | |  |
| `result` | object | yes | The method's result: a tool list for `tools/list`, a tool result for `tools/call`. |
| _one of_ | | |  |
| `result.tools` | array of object | yes | The tools the token may call and that are active now: its functions, then its external tools. |
| `result.tools.[]name` | string | yes | The tool's name, to pass as `params.name` in `tools/call`. |
| `result.tools.[]title` | string | no | A display name. |
| `result.tools.[]description` | string | no | What the tool does, when one is recorded. |
| `result.tools.[]inputSchema` | object | yes | A JSON Schema for the tool's `arguments`. Until a function declares one, it is `{ "type": "object" }`. |
| `result.tools.[]outputSchema` | object | no | A JSON Schema for the tool's result, when it declares one. |
| `result.nextCursor` | string | no | Pass as `params.cursor` to get the next page. Absent on the last page. |
| _or_ | | |  |
| `result.content` | array of object | yes | The result as MCP content blocks. For a function call, one text block holding the result as JSON. |
| `result.structuredContent` | object | yes | The result as structured data: the function's return value, or null when there is none. |
| `result.isError` | boolean | yes | True when the call ran and failed, in which case `structuredContent` carries the `K9O_*` error code and message. |
| `result._meta` | object | no | Extra details about the call, when there are any. A result from an external MCP server has `untrusted: true`. |
| _or_ | | |  |
| `jsonrpc` | enum ("2.0") | yes | Always `2.0`. |
| `id` | object | no | The request's id, echoed back. Omitted when the request had none. |
| _one of_ | | |  |
| _or_ | | |  |
| _or_ | | |  |
| `error` | object | yes |  |
| `error.code` | integer | yes | A JSON-RPC error code: -32600 (invalid request), -32601 (unknown method or tool), -32602 (invalid parameters) or -32603 (internal error). |
| `error.message` | string | yes | What went wrong. |
| `error.data` | object | no | Extra detail about the error, when there is any. |


## Errors

| HTTP | Code | When |
|---|---|---|
| 400 | `K9O_INVALID_REQUEST_SHAPE` | The request body could not be parsed as JSON-RPC. |
| 401 | `K9O_INVALID_TOKEN` | The token's audience is not this project's MCP resource URI, or the token is invalid or expired. |
| 403 | `K9O_FORBIDDEN` | The bearer is not a project_invoke_only token, or a tools/call names a tool outside the token's minted tool set. |

## Code samples

### cURL

```bash
curl -X POST 'https://<org>.api-<region>.k9o.io/@storefront/mcp' \
  -H 'Authorization: Bearer $K9O_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

### fetch

```javascript
const res = await fetch('https://<org>.api-<region>.k9o.io/@storefront/mcp', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.K9O_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({}),
});
const { data, meta } = await res.json();
```


Canonical page: https://docs.kilimanjaro.dev/api-playground/core/invoke-mcp-tools
