Skip to content
Back to MCP Settings

Connecting to Your Directory's MCP Server

This guide explains how to connect to your directory's built-in MCP (Model Context Protocol) server from various MCP clients. The MCP server allows AI agents and applications to interact with your directory programmatically.

What is the Model Context Protocol?

The Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to Large Language Models (LLMs). It follows a client-server architecture where:

  • MCP Hosts: Programs like AI tools that want to access data through MCP
  • MCP Clients: Protocol clients that maintain connections with servers
  • MCP Servers: Lightweight programs that expose specific capabilities through the standardized protocol
  • Data Sources: Your directory's data that MCP servers can securely access

Our implementation of MCP allows your AI agents and applications to seamlessly interact with your directory's data and functionality.

Overview

Every directory on Directories.ai comes with a built-in MCP server accessible at:

https://app.directories.ai/mcp

To connect to your directory's MCP server, you'll need:

  1. Your Directories.ai API Key
  2. Your Directory ID

Authentication

All requests to the MCP server require authentication using your Directories.ai API key. Include this key in the DIRECTORIES_AI_API_KEY header with every request.

DIRECTORIES_AI_API_KEY: your_api_key_here

You can generate and manage API keys in your Dashboard Settings.

Connection Methods

1. Using the FastMCP Client (Python)

The FastMCP client is the recommended way to connect to your directory's MCP server in Python:

from fastmcp import Client

# Initialize the client
client = Client("https://app.directories.ai/mcp", headers={
    "DIRECTORIES_AI_API_KEY": "your_api_key_here"
})

# List all directories you have access to
directories = client.call("list_directories")

# Work with a specific directory
listings = client.call("list_listings", directory_id="your_directory_id")

# Create a new listing
new_listing = client.call("create_listing", 
    directory_id="your_directory_id",
    name="New Business",
    description="A great new business listing",
    data={
        "address": "123 Main St",
        "phone": "555-123-4567",
        "website": "https://example.com"
    }
)

2. Using the MCP Client Library (JavaScript/TypeScript)

For JavaScript or TypeScript applications:

import { MCPClient } from '@directories/mcp-client';

// Initialize the client
const client = new MCPClient({
  apiUrl: 'https://app.directories.ai/mcp',
  apiKey: 'your_api_key_here'
});

// List all directories you have access to
const directories = await client.call('list_directories');

// Work with a specific directory
const listings = await client.call('list_listings', { directory_id: 'your_directory_id' });

// Create a new listing
const newListing = await client.call('create_listing', {
  directory_id: 'your_directory_id',
  name: 'New Business',
  description: 'A great new business listing',
  data: {
    address: '123 Main St',
    phone: '555-123-4567',
    website: 'https://example.com'
  }
});

3. Direct HTTP Requests

You can also make direct HTTP requests to the MCP server:

async function callDirectoriesMCP(method, params = {}) {
  const response = await fetch('https://app.directories.ai/mcp', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'DIRECTORIES_AI_API_KEY': 'your_api_key_here'
    },
    body: JSON.stringify({
      method,
      params
    })
  });
  
  return await response.json();
}

// Example usage
const directories = await callDirectoriesMCP('list_directories');
const listings = await callDirectoriesMCP('list_listings', { directory_id: 'your_directory_id' });

Available Methods

The MCP server provides the following methods:

| Method | Required Parameters | Description | |--------|---------------------|-------------| | list_directories | None | List all directories you have access to | | get_directory | directory_id | Get details about a specific directory | | list_listings | directory_id | List all listings in a directory | | get_listing | directory_id, listing_id | Get details about a specific listing | | create_listing | directory_id, name | Create a new listing in a directory | | update_listing | directory_id, listing_id | Update an existing listing | | list_categories | directory_id | List all categories in a directory | | search_listings | directory_id, query | Search for listings in a directory | | get_analytics | directory_id | Get analytics data for a directory | | get_directory_health | directory_id | Get health status of a directory |

Response Format

All MCP server responses follow this format:

{
  "method": "method_name",
  "result": {
    // Method-specific result data
  }
}

Error responses:

{
  "error": "Error message"
}

Building AI Agents with MCP

The MCP server is particularly useful for building AI agents that can interact with your directory. Here's a simple example of an AI agent that can discover and add new listings:

from fastmcp import Client
import openai

# Initialize clients
mcp_client = Client("https://app.directories.ai/mcp", headers={
    "DIRECTORIES_AI_API_KEY": "your_api_key_here"
})
openai_client = openai.Client(api_key="your_openai_api_key")

def discover_and_add_listing(directory_id, business_name):
    # Use AI to research the business
    response = openai_client.chat.completions.create(
        model="gpt-4",
        messages=[
            {"role": "system", "content": "You are a business research assistant."},
            {"role": "user", "content": f"Research {business_name} and provide details like address, phone, website, and a brief description in JSON format."}
        ]
    )
    
    # Parse the AI-generated data
    business_data = json.loads(response.choices[0].message.content)
    
    # Create the listing via MCP
    new_listing = mcp_client.call("create_listing", 
        directory_id=directory_id,
        name=business_name,
        description=business_data.get("description", ""),
        data={
            "address": business_data.get("address", ""),
            "phone": business_data.get("phone", ""),
            "website": business_data.get("website", "")
        }
    )
    
    return new_listing

Health Checks

You can verify the MCP server is operational by making a GET request:

GET https://app.directories.ai/mcp

This will return basic information about the server and its capabilities.

Troubleshooting

Common issues and solutions:

  1. Authentication Errors: Ensure your API key is valid and included in the DIRECTORIES_AI_API_KEY header.

  2. Permission Errors: Verify you have the necessary permissions for the directory you're trying to access.

  3. Rate Limiting: The MCP server has rate limits to prevent abuse. If you receive a 429 response, wait before making additional requests.

  4. Connection Issues: If you can't connect to the MCP server, check your network connection and verify the URL is correct.

For additional help, contact support@directories.ai or visit the Developer Documentation.