Skip to main content
POST/mcp

Invoke MCP Tools

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
projectSlug *path

The project's slug: the path segment after @.

It is unique within the org.

Request body
jsonrpc *"2.0"

Always 2.0.

idany

A value the caller chooses, echoed in the reply.

One of: string
or: number
or: null
method *string

The JSON-RPC method: tools/list or tools/call.

Any other method gets error -32601.

paramsobject

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
HTTPK9O CodeDescription
200The 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.
400K9O_INVALID_REQUEST_SHAPEThe request body could not be parsed as JSON-RPC.
401K9O_INVALID_TOKENThe token's audience is not this project's MCP resource URI, or the token is invalid or expired.
403K9O_FORBIDDENThe bearer is not a project_invoke_only token, or a tools/call names a tool outside the token's minted tool set.
Response body (200)
One of: object
jsonrpc *"2.0"

Always 2.0.

idany

The request's id, echoed back.

Omitted when the request had none.

One of: string
or: number
or: null
result *any

The method's result: a tool list for tools/list, a tool result for tools/call.

One of: object
tools *object[]

The tools the token may call and that are active now: its functions, then its external tools.

name *string

The tool's name, to pass as params.name in tools/call.

titlestring

A display name.

descriptionstring

What the tool does, when one is recorded.

inputSchema *object

A JSON Schema for the tool's arguments.

Until a function declares one, it is { "type": "object" }.

outputSchemaobject

A JSON Schema for the tool's result, when it declares one.

nextCursorstring

Pass as params.cursor to get the next page.

Absent on the last page.

or: object
content *object[]

The result as MCP content blocks.

For a function call, one text block holding the result as JSON.

structuredContent *any

The result as structured data: the function's return value, or null when there is none.

isError *boolean

True when the call ran and failed, in which case structuredContent carries the K9O_* error code and message.

_metaobject

Extra details about the call, when there are any.

A result from an external MCP server has untrusted: true.

or: object
jsonrpc *"2.0"

Always 2.0.

idany

The request's id, echoed back.

Omitted when the request had none.

One of: string
or: number
or: null
error *object
code *integer

A JSON-RPC error code: -32600 (invalid request), -32601 (unknown method or tool), -32602 (invalid parameters) or -32603 (internal error).

message *string

What went wrong.

dataany

Extra detail about the error, when there is any.

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

Showing example in cURL

Request example
{
  "jsonrpc": "2.0",
  "id": "string",
  "method": "string"
}
Response example (200)
{
  "jsonrpc": "2.0",
  "id": "string",
  "result": {
    "tools": [
      {
        "name": "string",
        "title": "string",
        "description": "string"
      }
    ],
    "nextCursor": "string"
  }
}

More in MCP