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.
| 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 |
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
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": {}
}
}'
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"}'
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}
}
}'
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"
}
}
}
}'
{{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"
}
}
}
}
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.
| 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:
See also
