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, sign in (or use an 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, Gemini 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 (apps) | OAuth: the client opens a "Sign in to Directories.ai" page and you approve it for one organization | | Auth (code, local clients) | Authorization: Bearer <your API key>, from Dashboard → Settings → Developer API |

That's the whole setup. The server speaks standard MCP — JSON-RPC 2.0 over Streamable HTTP (protocol versions 2024-11-05 through 2025-11-25) with OAuth 2.1 discovery — so any MCP-compliant client or SDK works without anything Directories.ai-specific.

Connecting an AI client

Claude (claude.ai, Desktop, mobile): Settings → Connectors → Add custom connector, paste https://directories.ai/mcp, then Connect and sign in.

ChatGPT: Settings → Apps & Connectors → Advanced settings → turn on Developer mode, then Create a connector with the URL and OAuth authentication.

Gemini CLI:

gemini mcp add --transport http directories-ai https://directories.ai/mcp

then run /mcp auth directories-ai in Gemini CLI to sign in. (Or add "directories-ai": { "httpUrl": "https://directories.ai/mcp" } under mcpServers in ~/.gemini/settings.json.)

Gemini API (your own app): the Google Gen AI SDK accepts an MCP client session as a tool, so Gemini models call Directories.ai tools directly:

from google import genai
from google.genai import types
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

client = genai.Client()  # GEMINI_API_KEY from the environment
async with streamablehttp_client(
    "https://directories.ai/mcp",
    headers={"Authorization": "Bearer <your Directories.ai API key>"},
) as (read, write, _):
    async with ClientSession(read, write) as session:
        await session.initialize()
        response = await client.aio.models.generate_content(
            model="gemini-2.5-flash",
            contents="List my directories and tell me which one needs attention.",
            config=types.GenerateContentConfig(tools=[session]),
        )
        print(response.text)

Claude Code:

claude mcp add --transport http directories-ai https://directories.ai/mcp

then run /mcp to sign in. Or install the Directories.ai plugin, which bundles the server with an operator skill.

Clients without OAuth (many local-model setups: Open WebUI, Goose, Cline, Continue, LM Studio, or a LiteLLM / OpenRouter-fronted gateway) use an API key in a header, e.g. 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 accept either form. Model routers choose which model answers; the MCP connection always lives in the client or gateway in front of them.

Apps you connected with OAuth are listed, and can be disconnected, under Dashboard → Settings → API Keys → Connected AI apps.

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.

Guided workflows ("playbooks": SEO and AI-visibility audits, content briefs, link-building outreach, digital PR, competitor research, reviews, conversion) are available as tools, list_playbooks and get_playbook, so they work in every client including ChatGPT and local models. Clients with a prompt menu also get them as MCP prompts: ranking_best_practices_audit, ai_era_design_review and run_playbook.

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, invalid or expired token. OAuth clients refresh automatically; if it persists, disconnect and reconnect. For API keys, check the key is active in Dashboard → Settings | | 403 mentioning embed keys | Embed keys are for public site scripts and don't work here; use an organization API key or OAuth | | 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.