Skip to content
Back to Docs

MCP Integration Guide — Directories.ai

Directories.ai is an MCP server. There's nothing to install or run — you point an AI client or your own code at one URL, authenticate with your API key, and it can manage your directory: listings, categories, content, claims, tasks, data imports, and proposed code changes.

Not a developer? The quick setup page walks through connecting Claude, ChatGPT, or Claude Code with copy-paste steps and no code. This page is the technical reference underneath that.

The three things you need

| | | |---|---| | Server URL | https://directories.ai/mcp | | Auth | Authorization: Bearer <your API key> | | API key | Generate one in Dashboard → Settings → Developer API |

That's the whole setup. The server speaks standard MCP — JSON-RPC 2.0 over Streamable HTTP, protocol version 2025-06-18 — so any MCP-compliant client or SDK works without anything Directories.ai-specific.

Connecting an AI client

Claude (claude.ai and Claude Desktop) and ChatGPT both support remote MCP servers directly via Settings → Connectors → Add custom connector: paste the URL above, set the Bearer token to your API key, done. Claude Code adds it from the CLI:

claude mcp add directories-ai \
  --transport http \
  --url https://directories.ai/mcp \
  --header "Authorization: Bearer your_api_key_here"

Or in a project's .mcp.json:

{
  "mcpServers": {
    "directories-ai": {
      "type": "http",
      "url": "https://directories.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${DIRECTORIES_AI_API_KEY}"
      }
    }
  }
}

Cursor and VS Code use the same shape, in .cursor/mcp.json or your client's MCP settings.

Connecting your own code

The protocol is JSON-RPC 2.0. Two calls matter for most integrations:

  • tools/list — enumerate available tools and their schemas
  • tools/call — invoke one, with { name, arguments }

TypeScript / JavaScript

async function callTool(name: string, args: Record<string, unknown> = {}) {
  const response = await fetch('https://directories.ai/mcp', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.DIRECTORIES_AI_API_KEY}`,
    },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: 1,
      method: 'tools/call',
      params: { name, arguments: args },
    }),
  });

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

const directories = await callTool('list_directories');
const listings = await callTool('list_listings', { directory_id: 'dir_abc123' });

Python (official MCP SDK)

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
import os

async with streamablehttp_client(
    "https://directories.ai/mcp",
    headers={"Authorization": f"Bearer {os.environ['DIRECTORIES_AI_API_KEY']}"},
) as (read, write, _):
    async with ClientSession(read, write) as session:
        await session.initialize()
        directories = await session.call_tool("list_directories", {})
        listings = await session.call_tool("list_listings", {"directory_id": "dir_abc123"})

TypeScript (official MCP SDK)

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const transport = new StreamableHTTPClientTransport(new URL('https://directories.ai/mcp'), {
  requestInit: { headers: { Authorization: `Bearer ${process.env.DIRECTORIES_AI_API_KEY}` } },
});

const client = new Client({ name: 'my-app', version: '1.0.0' });
await client.connect(transport);

const directories = await client.callTool({ name: 'list_directories', arguments: {} });

What's callable

Tools are grouped by area — listings & categories, content (articles/FAQs/pages), claims & outreach, tasks, data import, analytics/events, and repository proposals. Call tools/list against your own connection for the exact, current set with full schemas — it's the source of truth and changes as the server grows. Two guided prompts are also available via prompts/list / prompts/get: ranking_best_practices_audit and ai_era_design_review.

What's deliberately not callable

A fixed set of actions never goes through this server, regardless of how a request is phrased: reading or creating credentials (API keys, mail-provider keys, model keys, visitor-tracking keys), billing, member access, slug or custom-domain changes. Code changes only ever arrive as a proposed pull request — never a direct push. See the trust page for the full boundary.

Troubleshooting

| Symptom | Likely cause | |---|---| | 401 Unauthorized | Missing or invalid Bearer token — check the key is active in Dashboard → Settings | | 400 Bad Request | A required tool argument is missing or the wrong type — check tools/list's schema for that tool | | 404 in a tool result | The directory_id / listing_id doesn't exist or doesn't belong to your organization | | 429 Too Many Requests | Rate limited — retry with exponential backoff | | Connector adds but shows no tools | Some clients need the connector explicitly enabled per-conversation after adding it |

For help, contact support@directories.ai.