tools/call · CoreSpeed

POSThttps://api.corespeed.io/mcptools/call

Billing holds and API-key spend caps are checked before a metered tool executes. Those refusals arrive as tool-level errors inside HTTP 200, not as HTTP failures — see Errors. A suspended organization is refused earlier, with HTTP 403 org_suspended, before any tool runs. Where Smart Approvals is on, a write that needs a person's approval returns an approval receipt instead of running; call manage__approval_wait with its approval_id.

Authorizations

Authorizationstringheaderrequired: Bearer <token> — an MCP OAuth token, an sk-cs-… API key or sk-csa-… agent key, or a user session JWT. x-api-key: <sk-cs-…> is accepted in its place.
Acceptstringheaderrequired: application/json, text/event-stream — the Streamable HTTP transport requires both media types. This 2025-era request is answered as one text/event-stream event; its data: line is the JSON-RPC response.
Content-Typestringheaderrequired: application/json. The transport rejects anything else with 415.

Request

params.namestringrequired: A name returned by tools/list, e.g. memory__remember. A name that is unknown or not on this caller's surface is not an HTTP error: it comes back as HTTP 200 with a JSON-RPC error — code -32602, message Tool <name> not found — and no result. Nothing about a misspelled tool name shows up in the HTTP status.
params.argumentsobjectoptional: Arguments matching that tool's inputSchema. Optional in the MCP request schema — for a tool that takes none, omit it or send {} — but required in practice for every tool whose inputSchema has required properties. A schema violation is a tool-level error, not a transport error: HTTP 200 with result.isError: true and the text Input validation error: Invalid arguments for tool <name>: ….

Response fields

result.contentarrayrequired: Content blocks. Text tools return { "type": "text", "text": "…" }; media tools return signed artifact URLs.
result.isErrorbooleanoptional: true when the tool refused or failed. The HTTP status is still 200, so branch on this field before treating a call as successful.
result.structuredContent.errorobjectoptional: On a failed call, the machine-readable half: code — the value to branch on — plus only publishable facts (a provider's status, request_id, retry_after_seconds, the aliases to choose from, the allowed tools of a share). The text block is for the agent to read. Hold refusals carry their envelope as JSON in the text instead, and an approval receipt or refusal carries its facts in _meta. Every code is in Errors & status codes.
result._metaobjectoptional: CoreSpeed facts about the call: io.corespeed/hold on a hold refusal, and io.corespeed/approval on any result shaped by Smart Approvals.

The manage__* tools answer an API key as its principal, with the permissions the key was minted with — an agent key holds none. Two carry a rule of their own: manage__keys_create and manage__agents_key_create refuse every API key (api_key_cannot_mint — a key does not mint keys), and manage__agents_create and the environments_* writes refuse an agent principal (member_principal_required). The remote-connector lifecycle writes need connections:org, and manage__approval_wait answers only for the caller's own approval requests.

curl https://api.corespeed.io/mcp \
  -H "Authorization: Bearer $CORESPEED_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "memory__remember",
      "arguments": {
        "memory": "Rollout changes require a two-day review window.",
        "scope": "shared"
      }
    }
  }'

Tool succeeded

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Memory shared with the organization."
      }
    ],
    "structuredContent": {
      "id": "0b9a6f3e-…",
      "memory": "Rollout changes require a two-day review window.",
      "scope": "shared"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "More than one Notion account is connected (work, personal); pass `account` with one of those aliases (search)."
      }
    ],
    "structuredContent": {
      "error": { "code": "ambiguous_account", "aliases": ["work", "personal"] }
    },
    "isError": true
  }
}

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "An API key cannot mint a key: a key's spend cap does not carry to the keys it would mint. Mint it from a signed-in CoreSpeed session."
      }
    ],
    "structuredContent": { "error": { "code": "api_key_cannot_mint" } },
    "isError": true
  }
}