# 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](/docs/mcp)). 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.

```json
{
  "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](/docs/errors) explains each code and what to do.

## Example

```sh tab=curl
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"}]}'
```

```js tab=fetch
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](https://app.trytelltale.dev/openapi.json). Request builder: the [API explorer](/docs/api-explorer) shows every operation as curl; it sends requests only on a local dashboard.