API reference / MCP server

Claude MCP server

Connect Claude to LocalLeads via the Model Context Protocol. Claude can search Google Maps, enrich contacts, and manage credits — straight from a conversation.

Pick your path

Two ways to connect, depending on where you're using Claude.

Claude.ai

Claude.ai discovers LocalLeads through standard OAuth (Dynamic Client Registration + PKCE). All you need is our MCP URL.

1. In Claude.ai, open Settings → Connectors → Add custom connector.
2. Paste the URL:
   text

   https://leadsapi.postorbit.io/mcp

3. Sign in to LocalLeads on the authorization screen and approve.
4. You're back in Claude.ai with the LocalLeads tools wired up.

Claude API

The Messages API supports remote MCP servers via the mcp_servers field (beta header anthropic-beta: mcp-client-2025-11-20). Pass your ll_… API key as authorization_token:

curl https://api.anthropic.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-client-2025-11-20" \
  -d '{
    "model": "claude-opus-4-7",
    "max_tokens": 1024,
    "messages": [
      { "role": "user", "content": "Find me 20 plumbers in Manchester" }
    ],
    "mcp_servers": [
      {
        "type": "url",
        "url": "https://leadsapi.postorbit.io/mcp",
        "name": "localleads",
        "authorization_token": "ll_your_key_here"
      }
    ],
    "tools": [
      { "type": "mcp_toolset", "mcp_server_name": "localleads" }
    ]
  }'

Or with the TypeScript SDK:

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const response = await client.beta.messages.create({
  model: "claude-opus-4-7",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Find me 20 plumbers in Manchester" }],
  mcp_servers: [
    {
      type: "url",
      url: "https://leadsapi.postorbit.io/mcp",
      name: "localleads",
      authorization_token: process.env.LOCALLEADS_API_KEY!,
    },
  ],
  tools: [{ type: "mcp_toolset", mcp_server_name: "localleads" }],
  betas: ["mcp-client-2025-11-20"],
});

Claude Desktop, Cursor, VS Code

Local MCP clients spawn the server as a subprocess and talk over stdio. Install once with npm and add a config entry.

Claude Desktop

Edit your Claude Desktop config file:

• macOS  ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows  %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "localleads": {
      "command": "npx",
      "args": ["-y", "@localleads/mcp"],
      "env": {
        "LOCALLEADS_API_KEY": "ll_your_api_key_here"
      }
    }
  }
}

Restart Claude Desktop. The LocalLeads tool icon appears in the chat toolbar.

Cursor / VS Code

Add the server to .cursor/mcp.json or .vscode/mcp.json:

{
  "servers": {
    "localleads": {
      "command": "npx",
      "args": ["-y", "@localleads/mcp"],
      "env": {
        "LOCALLEADS_API_KEY": "ll_your_api_key_here"
      }
    }
  }
}

Global install

npm install -g @localleads/mcp
# then use "localleads-mcp" as the command instead of "npx"

Environment variables

Tools

Ten tools, identical across stdio and remote MCP. Claude picks the right one based on what you ask — you never call them by name.

OAuth & discovery

For MCP clients that auto-discover OAuth (Claude.ai, MCP Inspector, the official CLIs), we expose the standard well-known documents and OAuth endpoints.

Public clients use PKCE (S256); confidential clients use client_secret_basic. Access tokens are 1-hour TTL; refresh tokens rotate on every use.

Example conversation

Troubleshooting