MCP server: run DirectoryDuck from an AI agent

1. Create a key

In the dashboard, open Settings → API keys, name the key (for example "Claude Code") and pick its permissions. The key starts with ddmcp_ and is shown once: copy it then. It is not your directory's widget key, which can't be used here.

2. Connect your client

Server URL https://directoryduck.com/api/mcp (Streamable HTTP), with the key in an Authorization: Bearer header.

Claude Code

claude mcp add --transport http directoryduck https://directoryduck.com/api/mcp \
  --header "Authorization: Bearer ddmcp_YOUR_KEY"

Cursor

Add this to .cursor/mcp.json in a project, or ~/.cursor/mcp.json for every project, then restart Cursor:

{
  "mcpServers": {
    "directoryduck": {
      "url": "https://directoryduck.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ddmcp_YOUR_KEY"
      }
    }
  }
}

Claude Desktop

Claude's Connectors screen signs in with OAuth, which this server does not offer yet, so connect through the open-source mcp-remote bridge (it needs Node.js). In Claude Desktop, open Settings → Developer → Edit Config, add this to claude_desktop_config.json and restart Claude:

{
  "mcpServers": {
    "directoryduck": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://directoryduck.com/api/mcp",
        "--header",
        "Authorization:${DIRECTORYDUCK_AUTH}"
      ],
      "env": {
        "DIRECTORYDUCK_AUTH": "Bearer ddmcp_YOUR_KEY"
      }
    }
  }
}

Any other MCP client

Point it at the URL and send the header on every request. The server is stateless: it speaks MCP 2026-07-28 and serves 2025-era clients too; there is no session to open or close and no SSE stream to keep.

POST https://directoryduck.com/api/mcp
Authorization: Bearer ddmcp_YOUR_KEY
Content-Type: application/json
Accept: application/json, text/event-stream

3. Ask for a directory

For example: "Create a directory of dog groomers in Austin, find about 15 with DirectoryDuck, publish them and give me the embed snippet." The agent calls create_directory, run_discovery, get_discovery_job until the job is done, publish_listings and get_embed_snippet.

Credits

Only run_discovery spends credits, the same credits and the same prices as discovery in the dashboard: 10 to start, 1 for the web search and 2 per business found. Duplicates of listings you already have are skipped and cost nothing. The most a job can cost: small 41 credits (up to 15 businesses), medium 91 (40), large 211 (100). A job needs at least 13 credits left to start.

Every other tool costs no credits. Publishing listings costs nothing.

Limits

• Requests per minute per key: Free 10, Starter 30, Growth 60, Pro 120. Every MCP request counts, listing the tools and the read-only tools included, so each tool call costs one. Over the limit you get HTTP 429 with a Retry-After header.
• One JSON-RPC message per request: batches (JSON arrays) are refused with HTTP 400. Request bodies are limited to 256 KiB. The server takes POST only and keeps no stream open.
• One discovery job per directory at a time.
• Your plan's directory and listing limits apply (Starter 1 directory and 500 listings, Growth 5 and 2,000 each, Pro unlimited).
• Up to 5 active keys per account.
• AI discovery pauses for everyone when DirectoryDuck's monthly AI budget is reached; run_discovery then says so and charges nothing.

Permissions and security

• mcp:read: List listings, read discovery jobs and get the embed snippet.
• mcp:write: Create directories, add and publish listings, connect a domain.
• mcp:spend: Run AI discovery, which uses credits like the dashboard does.
• mcp:billing: Start a checkout (returns a link you open and pay in your browser).
• A key acts as you. We store only a fingerprint (SHA-256) of it, so a lost key can't be shown again: rotate it (new key, same permissions, the old one stops at once) or revoke it in Settings → API keys.
• start_checkout only returns a Stripe Checkout link; you open it and pay in your browser. Nothing is charged inside the chat.

Errors

A refused tool call comes back as a tool result marked as an error, with a code and what to do next: invalid_input, not_found, scope_missing, plan_required (a Free key calling a tool that needs Starter and up), limit_reached, conflict (for example a discovery already running in that directory), refused (not enough credits, the AI budget, a domain that can't be used), unavailable or failed. A missing, wrong or revoked key is HTTP 401; over the rate limit, HTTP 429.