MCP API Reference

Overview

Closer Mode exposes a hosted Model Context Protocol (MCP) endpoint at POST /api/mcp. Any MCP-compatible client can call it using a Bearer API key.

The endpoint is stateless (no session, no SSE). Each request is a self-contained JSON-RPC call that returns a plain JSON response. This makes it easy to integrate with Claude Desktop, custom scripts, or any HTTP client.

POST https://app.closermode.ai/api/mcp
Content-Type: application/json
Authorization: Bearer mcp_your-org_<32-char-key>

Getting a Key

MCP API keys are managed by organization admins in the Closer Mode dashboard.

Authentication

Pass your MCP API key as a Bearer token in every request:

Authorization: Bearer mcp_your-org_a1b2c3d4e5f6...

Keys follow the format mcp_<org-slug>_{32-hex-chars}. The plaintext key is never stored — only a SHA-256 hash is kept at rest. If your key is compromised, revoke it from the dashboard and generate a new one.

Claude Desktop Setup

Add Closer Mode as an MCP server in your Claude Desktop configuration file:

{
  "mcpServers": {
    "closer-mode": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://app.closermode.ai/api/mcp",
        "--header",
        "Authorization:${AUTH_TOKEN}"
      ],
      "env": {
        "AUTH_TOKEN": "Bearer mcp_your-org_<32-char-key>"
      }
    }
  }
}

Example Use Cases

Once connected, you can ask Claude natural-language questions about your call data. Here are real examples of what you can do.

Direct API Usage

You can call the MCP endpoint directly from any HTTP client — no MCP SDK required. Send a standard MCP JSON-RPC request body with your Bearer token.

Search calls with curl

curl -X POST https://app.closermode.ai/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer mcp_your-org_<key>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "calls_search",
      "arguments": {
        "status": "scored",
        "minScore": 0,
        "maxScore": 60,
        "limit": 10
      }
    }
  }'

Fetch a transcript with Node.js

const res = await fetch("https://app.closermode.ai/api/mcp", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer mcp_your-org_<key>",
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "tools/call",
    params: {
      name: "calls_transcript",
      arguments: { callId: "9db7cebd-e628-4415-948c-11ede6187636" },
    },
  }),
});

const { result } = await res.json();
const { transcript } = JSON.parse(result.content[0].text);

List available tools

curl -X POST https://app.closermode.ai/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer mcp_your-org_<key>" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'

Available Tools

All tools are read-only. They are scoped to your organization — cross-org access is not possible.

Call tools

Pattern tools

Rubric tools

calls_search — input parameters

Rate Limits

Each API key is limited to 60 requests per minute using a sliding window algorithm. The limit is per-key, not per-org.

When the limit is exceeded, the endpoint returns HTTP 429 with { "error": "Rate limit exceeded. Max 60 requests/minute." }. Back off for the duration indicated by the Retry-After header.

Pagination

List tools return a hasMore boolean. When hasMore: true, there are additional results beyond the current page.

{
  "data": [
    { "id": "uuid-1", "title": "Call with Acme Corp", ... },
    { "id": "uuid-2", "title": "Follow-up with Jane", ... }
  ],
  "hasMore": true
}

To fetch the next page, pass a smaller startDateor endDate to narrow the window. Cursor-based pagination is planned for a future release.

Error Codes

{ "error": "Unauthorized" }

{ "error": "Rate limit exceeded. Max 60 requests/minute." }

{ "error": "Invalid request" }

{ "error": "Internal server error" }

Known Limitations