Skip to main content

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.

​
thinnestAI MCP Server

thinnestAI ships a production Model Context Protocol 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.
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).

​
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

ToolTypeWhat it does
list_agentsReadList voice/chat agents in your workspace
get_agentReadFetch one agent’s full config by public_id
dispatch_callWritePlace an outbound voice call from one of your numbers
list_callsReadRecent voice sessions, newest first; filter by agent or status
get_callReadFull transcript + recording + cost breakdown for one call
upload_knowledge_textWriteAdd plain text to a knowledge source you own
get_billing_summaryReadWallet 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.
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.

​
Quick test

​
1. Health check (no auth required)

curl https://api.thinnest.ai/mcp
Returns discovery metadata: server name, version, protocol version, transport, auth scheme.

​
2. Initialize handshake

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

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

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: 
{
  "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: 
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: 
{
  "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: 
{
  "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.
CodeMeaningWhen
-32700Parse errorBody isn’t valid JSON
-32600Invalid requestBad JSON-RPC envelope
-32601Method not foundUnknown method or tool name
-32602Invalid paramsPydantic validation failed
-32603Internal errorUnhandled exception (correlation ID in server logs)
-32000Server errorTool raised a business-logic error
-32001Not foundResource doesn’t exist or doesn’t belong to you
-32002ValidationTool-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:
SurfaceURL
MCP server cardhttps://thinnest.ai/.well-known/mcp/server-card.json
A2A agent cardhttps://thinnest.ai/.well-known/agent-card.json
Agent skills indexhttps://thinnest.ai/.well-known/agent-skills/index.json
RFC 9727 API cataloghttps://thinnest.ai/.well-known/api-catalog
LLM indexhttps://thinnest.ai/llms.txt

​
See also