Record tool calls through your MCP server (Telltale for MCP servers)

POST /api/v1/mcp/calls · operationId recordMcpCalls

For developers: your server sends this request with a server key; it is not a button in the dashboard. To see the same information without code, open Tools › All tools in the dashboard.

Shapes only: unknown fields are refused, never dropped, so no argument, result, error text or header can be stored. Each call is one approved-route call with channel mcp, once per eventId; a bad call is rejected alone. Sent by the MCP adapter (/adapters/v1/mcp.js; see Telltale for MCP servers). There is no field for arguments, results or error text.

#Authentication

Send Authorization: Bearer YOUR_SERVER_KEY (siteServerKey: Site server key in Authorization: Bearer <key> (the scheme is case-insensitive and required; a bare key is 401). Shown once on creation or rotation. Publishable keys cannot authenticate). Keep the server key in server-only configuration; never send it to a browser.

#Request body

Content-Type: application/json (required)

• sdk (object, optional)
• sdk.name (string, required)
• sdk.version (string, optional)
• server (object, optional)
• server.name (string, required)
• server.version (string, optional)
• dropped (integer, optional) · minimum 0
• calls (object[], required)
• calls[].eventId (string, required) · pattern ^[A-Za-z0-9_-]{8,128}$
• calls[].tool (string, required) · pattern ^[A-Za-z0-9_./-]{1,128}$
• calls[].startedAt (integer, required)
• calls[].endedAt (integer, required)
• calls[].responseBytes (integer | null, optional) · minimum 0, maximum 1000000000000
• calls[].responseTokens (integer | null, optional) · minimum 0, maximum 1000000000000
• calls[].outcome ("ok" | "error" | "refused" | "cancelled", required)
• calls[].errorClass ("tool_error" | "invalid_params" | "unknown_tool" | "internal_error" | "timeout" | "other", optional)
• calls[].refusedBy ("deny" | "hold" | "unreachable", optional)
• calls[].client (object, optional)
• calls[].client.name (string, required) · maxLength 64
• calls[].client.version (string, optional) · maxLength 32
• calls[].accountId (string, optional) · maxLength 512
• calls[].userId (string, optional) · maxLength 512
• calls[].session (object, optional)
• calls[].session.key (string, required) · pattern ^[a-f0-9]{32,64}$
• calls[].session.source ("customer" | "transport" | "derived", required)
• calls[].reason (string, optional) · maxLength 280
• calls[].decisionId (string, optional)
• calls[].tokenId (string, optional)
• calls[].tags (object, optional): Categories only: keys that suggest personal data or secrets, identifier-like values and free text are dropped and counted in tagsDropped.

{
  "server": {
    "name": "docs-server",
    "version": "1.4.0"
  },
  "calls": [
    {
      "eventId": "call_00000001",
      "tool": "search_docs",
      "startedAt": 1794268800000,
      "endedAt": 1794268801200,
      "outcome": "ok",
      "client": {
        "name": "claude-ai",
        "version": "1.0"
      },
      "accountId": "acct_456"
    }
  ]
}

#Responses

• 200: Success · body object
• 400: bad_request: the request is invalid; message says what to fix and field names the request field · body Error
• 401: unauthorized (missing or invalid server key, missing Bearer scheme) · body Error
• 403: forbidden: the call came from a browser page or another Site; call from your server with this Site’s server key · body Error
• 404: not_found: unknown path, or an ID in the path that is not on this Site · body Error
• 409: conflict: an eventId was already used with different facts; the call is rejected alone in rejected[] · body Error
• 413: payload_too_large: the request body exceeds 131072 bytes · body Error
• 429: rate_limited: wait for Retry-After · body Error · headers Retry-After
• 500: internal_error: fail the protected action; do not retry automatically · body Error
• 503: service_unavailable: temporarily unavailable; only verify retries · body Error

#Success body fields

• accepted (integer, required)
• replayed (integer, required)
• rejected (object[], required)
• rejected[].index (integer, required)
• rejected[].field (string | null, required)
• rejected[].error (string, required)

Failures are not verdicts. Error bodies follow the Error schema: code is one of bad_request, unauthorized, session_reinit_required, forbidden, not_found, conflict, identity_required, payload_too_large, rate_limited, internal_error, service_unavailable, request_failed, approval_invalid, approval_used, approval_expired, approval_mismatch, step_up_not_held, step_up_mismatch, step_up_settled, step_up_expired, step_up_superseded, agent_tokens_disabled, tool_not_approved, tool_not_read_only. Errors and retries explains each code and what to do.

#Example

curl -sS -X POST 'https://app.trytelltale.dev/api/v1/mcp/calls' \
  -H "Authorization: Bearer $TELLTALE_SERVER_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"server":{"name":"docs-server","version":"1.4.0"},"calls":[{"eventId":"call_00000001","tool":"search_docs","startedAt":1794268800000,"endedAt":1794268801200,"outcome":"ok","client":{"name":"claude-ai","version":"1.0"},"accountId":"acct_456"}]}'

const response = await fetch("https://app.trytelltale.dev/api/v1/mcp/calls", {
  method: "POST",
  headers: {
    Authorization: 'Bearer ' + process.env.TELLTALE_SERVER_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "server": {
      "name": "docs-server",
      "version": "1.4.0"
    },
    "calls": [
      {
        "eventId": "call_00000001",
        "tool": "search_docs",
        "startedAt": 1794268800000,
        "endedAt": 1794268801200,
        "outcome": "ok",
        "client": {
          "name": "claude-ai",
          "version": "1.0"
        },
        "accountId": "acct_456"
      }
    ]
  }),
  signal: AbortSignal.timeout(5000)
});
const result = await response.json();

Machine-readable contract: openapi.json. Request builder: the API explorer shows every operation as curl; it sends requests only on a local dashboard.