> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thinnest.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Expose your thinnestAI workspace to any MCP client (Claude Desktop, ChatGPT, Cursor, custom agents) via the Model Context Protocol.

# thinnestAI MCP Server

thinnestAI ships a production [Model Context Protocol](https://modelcontextprotocol.io) server. Any MCP-compatible client — Claude Desktop, ChatGPT MCP Apps, Cursor, custom agentic workflows — can plug in and drive the platform as one tool among many. Manage agents, inspect calls, upload knowledge, check billing — without writing REST glue code.

<Note>
  **This page is about the MCP *server* — thinnestAI *exposed as* MCP tools.**
  If you're looking for the MCP *client* (your voice agent *consuming* external MCP servers during a call), see [MCP Tool (voice)](/docs/voice/tools/mcp-voice).
</Note>

## Endpoint

```
POST  https://api.thinnest.ai/mcp
GET   https://api.thinnest.ai/mcp        (discovery metadata)
```

* **Transport:** Streamable HTTP (single POST endpoint accepting JSON-RPC 2.0 messages)
* **Protocol version:** `2025-11-25`
* **Auth:** Bearer token in the `Authorization` header. Use the same `thns_sk_*` platform API key as the REST API — no separate credential type.

Get a key: **Dashboard → Settings → API Keys → Create key**.

## Tools

| Tool                    | Type  | What it does                                                   |
| ----------------------- | ----- | -------------------------------------------------------------- |
| `list_agents`           | Read  | List voice/chat agents in your workspace                       |
| `get_agent`             | Read  | Fetch one agent's full config by `public_id`                   |
| `dispatch_call`         | Write | Place an outbound voice call from one of your numbers          |
| `list_calls`            | Read  | Recent voice sessions, newest first; filter by agent or status |
| `get_call`              | Read  | Full transcript + recording + cost breakdown for one call      |
| `upload_knowledge_text` | Write | Add plain text to a knowledge source you own                   |
| `get_billing_summary`   | Read  | Wallet balance + 30-day usage rollup in INR                    |

Each tool's input schema (parameter types, required vs optional, validation rules — e.g. E.164 phone-number format) is exposed via `tools/list`, so your MCP client renders the right form automatically and rejects bad inputs before they hit the server.

<Note>
  **`dispatch_call` prerequisites:** the `from_number` must be a phone number you own (imported via `/phone-numbers` or BYOK). For Indian destinations (+91…), the calling number needs a registered DLT template. The call is billed against your wallet at platform fee + provider pass-through.
</Note>

## Quick test

### 1. Health check (no auth required)

```bash theme={null}
curl https://api.thinnest.ai/mcp
```

Returns discovery metadata: server name, version, protocol version, transport, auth scheme.

### 2. Initialize handshake

```bash theme={null}
curl -X POST https://api.thinnest.ai/mcp \
  -H "Authorization: Bearer thns_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-11-25",
      "clientInfo": {"name": "curl", "version": "1.0"},
      "capabilities": {}
    }
  }'
```

### 3. List tools

```bash theme={null}
curl -X POST https://api.thinnest.ai/mcp \
  -H "Authorization: Bearer thns_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
```

### 4. Call a tool

```bash theme={null}
curl -X POST https://api.thinnest.ai/mcp \
  -H "Authorization: Bearer thns_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "list_agents",
      "arguments": {"limit": 5}
    }
  }'
```

The response wraps the tool result in MCP's `content` envelope:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {"type": "text", "text": "{\"agents\": [...], \"count\": 5, \"limit\": 5, \"offset\": 0}"}
    ],
    "isError": false
  }
}
```

### 5. Place an outbound call

The headline tool — an external MCP client can literally make a phone call:

```bash theme={null}
curl -X POST https://api.thinnest.ai/mcp \
  -H "Authorization: Bearer thns_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "dispatch_call",
      "arguments": {
        "agent_id": "agnt_abc123",
        "from_number": "+919876500000",
        "to_number": "+919876543210",
        "custom_variables": {
          "customer_name": "Priya",
          "amount": "₹4,250"
        }
      }
    }
  }'
```

Variables surface inside the agent's prompt as `{{customer_name}}`, `{{amount}}`, etc. Returns a `session_id` you can pass to `get_call` once the call completes.

## Connecting Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, or `%APPDATA%\Claude\claude_desktop_config.json` on Windows:

```json theme={null}
{
  "mcpServers": {
    "thinnestai": {
      "url": "https://api.thinnest.ai/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer thns_sk_YOUR_KEY"
      }
    }
  }
}
```

Restart Claude Desktop. The thinnestAI tools appear in the tool picker — Claude can now manage your agents, look up call transcripts, and check usage on demand.

## Connecting Cursor

Cursor → Settings → MCP servers → Add:

```json theme={null}
{
  "thinnestai": {
    "url": "https://api.thinnest.ai/mcp",
    "auth": "Bearer thns_sk_YOUR_KEY"
  }
}
```

## Connecting ChatGPT MCP Apps

In the ChatGPT desktop app, **Settings → MCP Servers → Add Server**:

* **URL:** `https://api.thinnest.ai/mcp`
* **Auth:** Bearer `thns_sk_YOUR_KEY`
* **Transport:** Streamable HTTP

## Error codes

All errors follow the JSON-RPC 2.0 spec. The HTTP response stays `200 OK` when the transport is healthy — errors live inside the `error` field.

| Code     | Meaning          | When                                                                                                      |
| -------- | ---------------- | --------------------------------------------------------------------------------------------------------- |
| `-32700` | Parse error      | Body isn't valid JSON                                                                                     |
| `-32600` | Invalid request  | Bad JSON-RPC envelope                                                                                     |
| `-32601` | Method not found | Unknown method or tool name                                                                               |
| `-32602` | Invalid params   | Pydantic validation failed                                                                                |
| `-32603` | Internal error   | Unhandled exception (correlation ID in server logs)                                                       |
| `-32000` | Server error     | Tool raised a business-logic error                                                                        |
| `-32001` | Not found        | Resource doesn't exist or doesn't belong to you                                                           |
| `-32002` | Validation       | Tool-level validation (e.g. phone number not E.164, knowledge\_base\_id not numeric, agent not published) |

## Auth & tenant isolation

* Every tool call resolves `Authorization: Bearer thns_sk_*` to a workspace via the same path as the REST API.
* Every tool that touches tenant data (`get_agent`, `dispatch_call`, `list_calls`, `get_call`, `upload_knowledge_text`) verifies the resource belongs to the caller before reading or writing. A "not found" response covers both missing and not-yours cases so the server doesn't leak the existence of other workspaces' IDs.
* API key rotation, scoping, and revocation work exactly the same as for REST. Rotate via **Dashboard → Settings → API Keys**.

## Rate limits

MCP traffic shares the per-API-key REST rate limits (currently 60 req/min, 100K tokens/min per key). Heavy users should split traffic across keys for now; per-tool limits are on the roadmap.

## Discovery

The MCP server is advertised in several discovery surfaces so agents can find it without configuration:

| Surface              | URL                                                                                                                |
| -------------------- | ------------------------------------------------------------------------------------------------------------------ |
| MCP server card      | [https://thinnest.ai/.well-known/mcp/server-card.json](https://thinnest.ai/.well-known/mcp/server-card.json)       |
| A2A agent card       | [https://thinnest.ai/.well-known/agent-card.json](https://thinnest.ai/.well-known/agent-card.json)                 |
| Agent skills index   | [https://thinnest.ai/.well-known/agent-skills/index.json](https://thinnest.ai/.well-known/agent-skills/index.json) |
| RFC 9727 API catalog | [https://thinnest.ai/.well-known/api-catalog](https://thinnest.ai/.well-known/api-catalog)                         |
| LLM index            | [https://thinnest.ai/llms.txt](https://thinnest.ai/llms.txt)                                                       |

## See also

* [MCP tool for voice agents](/docs/voice/tools/mcp-voice) — *the other side*: your voice agent calling external MCP servers during a phone call
* [API authentication](/docs/authentication)
* [A2A protocol](/docs/a2a/index)