MCP Integration

Complete guide to integrating AIDP with Model Context Protocol (MCP).

What is MCP?

Model Context Protocol (MCP) is an open standard for connecting AI assistants with external data sources and tools. Think of it as "USB-C for AI" - a universal way for AI platforms to access business data.

MCP Protocol Flow

Key Benefits:

• ✅ Standardized protocol (works with Claude, ChatGPT, etc.)

• ✅ Secure and controlled access

• ✅ Real-time data updates

• ✅ Native AI integration

Quick Start

1. Install MCP SDK

npm install @modelcontextprotocol/sdk @aidp-protocol/core

2. Create MCP Server

import { MCPServer } from '@modelcontextprotocol/sdk';
import { AIDPToolCatalog } from '@aidp-protocol/core';

const server = new MCPServer({
  name: 'my-business-mcp-server',
  version: '1.0.0',
  description: 'MCP server for my business',
});

// Register AIDP standard tools
server.registerTools(AIDPToolCatalog.getStandardTools());

// Start server
server.listen(3000);
console.log('MCP server running on port 3000');

3. Test Your Server

# Test with MCP client
npx @modelcontextprotocol/inspector http://localhost:3000

AIDP Standard Tools

AIDP Schema defines 8 standard MCP tools that all implementations should support:

Discovery Tools

search_businesses

{
  name: 'search_businesses',
  description: 'Search for local businesses',
  parameters: {
    query: 'string (optional)',
    location: {
      city: 'string',
      country: 'string',
      coordinates: { lat: 'number', lon: 'number', radius: 'number' }
    },
    category: 'string (optional)',
    filters: {
      priceRange: 'string',
      rating: 'number',
      verified: 'boolean',
      openNow: 'boolean'
    }
  }
}

get_business_details

{
  name: 'get_business_details',
  description: 'Get detailed business information',
  parameters: {
    businessId: 'string (required)',
    includeExclusiveContent: 'boolean (default: true)'
  }
}

compare_businesses

{
  name: 'compare_businesses',
  description: 'Compare multiple businesses side-by-side',
  parameters: {
    businessIds: 'string[] (2-5 businesses)',
    comparisonCriteria: 'string[] (optional)'
  }
}

Booking Tools

check_availability

{
  name: 'check_availability',
  description: 'Check real-time availability',
  parameters: {
    businessId: 'string (required)',
    serviceId: 'string (required)',
    date: 'string (YYYY-MM-DD)',
    duration: 'number (minutes)',
    partySize: 'number'
  }
}

create_booking

{
  name: 'create_booking',
  description: 'Create a new booking',
  parameters: {
    businessId: 'string (required)',
    serviceId: 'string (required)',
    scheduledAt: 'string (ISO 8601)',
    customerInfo: {
      name: 'string',
      email: 'string',
      phone: 'string'
    },
    specialRequests: 'string (optional)'
  }
}

submit_lead

{
  name: 'submit_lead',
  description: 'Submit inquiry for quote-based services',
  parameters: {
    businessId: 'string (required)',
    serviceId: 'string (optional)',
    customerInfo: { ... },
    message: 'string (required)',
    urgency: 'low | medium | high'
  }
}

Review Tools

get_reviews

{
  name: 'get_reviews',
  description: 'Get business reviews',
  parameters: {
    businessId: 'string (required)',
    filters: {
      rating: 'number',
      verified: 'boolean',
      hasPhotos: 'boolean'
    },
    sort: 'recent | helpful | rating_high | rating_low',
    limit: 'number (default: 10)'
  }
}

Analytics Tools

get_upstream_metrics

{
  name: 'get_upstream_metrics',
  description: 'Get upstream visibility metrics',
  parameters: {
    businessId: 'string (required)',
    startDate: 'string (YYYY-MM-DD)',
    endDate: 'string (YYYY-MM-DD)',
    metrics: 'string[] (impressions, citations, comparisons, zero_click)'
  }
}

View complete tool catalog →

Implementation Guide

Step 1: Set Up Server

Create your MCP server with AIDP tools:

import { MCPServer } from '@modelcontextprotocol/sdk';
import { AIDPClient } from '@aidp-protocol/core';

const aidpClient = new AIDPClient({
  apiKey: process.env.AIDP_API_KEY,
});

const server = new MCPServer({
  name: 'aidp-mcp-server',
  version: '1.0.0',
});

// Register search tool
server.registerTool({
  name: 'search_businesses',
  description: 'Search for local businesses',
  parameters: {
    type: 'object',
    properties: {
      query: { type: 'string' },
      location: {
        type: 'object',
        properties: {
          city: { type: 'string' },
          country: { type: 'string' },
        },
        required: ['city', 'country'],
      },
    },
  },
  handler: async (params) => {
    const results = await aidpClient.businesses.search(params);
    return {
      businesses: results.businesses.map((b) => ({
        id: b.id,
        name: b.name,
        category: b.category,
        rating: b.trust.averageRating,
        location: b.location,
      })),
    };
  },
});

Step 2: Implement Tool Handlers

Each tool needs a handler function:

// Get business details
server.registerTool({
  name: 'get_business_details',
  description: 'Get detailed business information',
  parameters: {
    type: 'object',
    properties: {
      businessId: { type: 'string' },
      includeExclusiveContent: { type: 'boolean', default: true },
    },
    required: ['businessId'],
  },
  handler: async (params) => {
    const business = await aidpClient.businesses.getById(params.businessId, {
      includeExclusiveContent: params.includeExclusiveContent,
    });

    return {
      id: business.id,
      name: business.name,
      description: business.description,
      services: business.services,
      exclusiveContent: business.aiOptimization?.exclusiveContent,
      trust: business.trust,
    };
  },
});

Step 3: Add Security

Implement authentication and rate limiting:

import { RateLimiter } from '@aidp-protocol/core';

const rateLimiter = new RateLimiter({
  windowMs: 60000, // 1 minute
  maxRequests: 100,
});

server.use(async (req, res, next) => {
  // Verify API key
  const apiKey = req.headers['authorization']?.replace('Bearer ', '');
  if (!apiKey || !(await verifyApiKey(apiKey))) {
    return res.status(401).json({ error: 'Unauthorized' });
  }

  // Rate limiting
  const allowed = await rateLimiter.checkLimit(apiKey);
  if (!allowed) {
    return res.status(429).json({ error: 'Too many requests' });
  }

  next();
});

Step 4: Deploy

Deploy your MCP server:

# Using Docker
docker build -t my-mcp-server .
docker run -p 3000:3000 my-mcp-server

# Using Node.js
npm start

Testing Your MCP Server

Using MCP Inspector

npx @modelcontextprotocol/inspector http://localhost:3000

Using AIDP Validator

npm install -g @aidp-protocol/core

# Validate MCP server
aidp-validate mcp http://localhost:3000

# Check AIDP compliance
aidp-validate compliance --url http://localhost:3000

Manual Testing

import { MCPClient } from '@modelcontextprotocol/sdk';

const client = new MCPClient({
  serverUrl: 'http://localhost:3000',
});

// List available tools
const tools = await client.listTools();
console.log('Available tools:', tools);

// Execute search
const result = await client.executeTool('search_businesses', {
  location: { city: 'Portland', country: 'USA' },
  category: 'restaurants',
});
console.log('Search results:', result);

Best Practices

Security

✅ Do:

• Validate all inputs

• Sanitize PII in responses

• Implement rate limiting

• Use HTTPS in production

• Rotate API keys regularly

❌ Don't:

• Expose internal errors

• Return sensitive data

• Allow unlimited requests

• Use HTTP in production

• Hardcode credentials

Performance

✅ Do:

• Cache frequently accessed data

• Use connection pooling

• Implement pagination

• Monitor response times

• Set appropriate timeouts

❌ Don't:

• Make unnecessary database queries

• Return large payloads

• Block on slow operations

• Ignore memory leaks

• Skip error handling

Tool Design

✅ Do:

• Keep tools focused and single-purpose

• Use clear, descriptive names

• Provide detailed descriptions

• Include usage examples

• Return structured data

❌ Don't:

• Create overly complex tools

• Use ambiguous names

• Skip documentation

• Return unstructured text

• Mix multiple concerns

Advanced Topics

Custom Tools

Add business-specific tools:

server.registerTool({
  name: 'get_menu_specials',
  description: "Get today's menu specials",
  parameters: {
    type: 'object',
    properties: {
      date: { type: 'string', format: 'date' },
    },
  },
  handler: async (params) => {
    const specials = await getMenuSpecials(params.date);
    return { specials };
  },
});

Webhooks

Notify AI platforms of updates:

import { WebhookService } from '@aidp-protocol/core';

const webhooks = new WebhookService();

// Register webhook
await webhooks.register({
  url: 'https://ai-platform.com/webhooks/aidp',
  events: ['profile.updated', 'booking.created'],
});

// Trigger webhook
await webhooks.trigger('profile.updated', {
  businessId: 'biz_abc123',
  changes: ['description', 'hours'],
});

Monitoring

Track MCP server performance:

import { MCPMetrics } from '@aidp-protocol/core';

const metrics = new MCPMetrics();

server.use(async (req, res, next) => {
  const start = Date.now();

  res.on('finish', () => {
    const duration = Date.now() - start;
    metrics.recordRequest({
      tool: req.body.tool,
      duration,
      status: res.statusCode,
    });
  });

  next();
});

Troubleshooting

Common Issues

Tool not found

Error: Tool 'search_businesses' not found

Solution: Ensure tool is registered with correct name

Authentication failed

Error: 401 Unauthorized

Solution: Check API key is valid and included in headers

Rate limit exceeded

Error: 429 Too Many Requests

Solution: Reduce request frequency or upgrade plan

Timeout

Error: Request timeout

Solution: Optimize slow queries, increase timeout, or use caching

Examples

Complete MCP Server

import { MCPServer } from '@modelcontextprotocol/sdk';
import { AIDPClient } from '@aidp-protocol/core';
import { RateLimiter } from '@aidp-protocol/core';

const aidp = new AIDPClient({ apiKey: process.env.AIDP_API_KEY });
const rateLimiter = new RateLimiter({ maxRequests: 100, windowMs: 60000 });

const server = new MCPServer({
  name: 'aidp-mcp-server',
  version: '1.0.0',
});

// Middleware
server.use(async (req, res, next) => {
  const apiKey = req.headers['authorization']?.replace('Bearer ', '');
  if (!(await rateLimiter.checkLimit(apiKey))) {
    return res.status(429).json({ error: 'Too many requests' });
  }
  next();
});

// Register tools
server.registerTool({
  name: 'search_businesses',
  description: 'Search for local businesses',
  parameters: {
    /* ... */
  },
  handler: async (params) => {
    return await aidp.businesses.search(params);
  },
});

server.registerTool({
  name: 'get_business_details',
  description: 'Get detailed business information',
  parameters: {
    /* ... */
  },
  handler: async (params) => {
    return await aidp.businesses.getById(params.businessId);
  },
});

// Start server
server.listen(3000);

Resources

• MCP Specification

• AIDP MCP Tools

• Code Examples

• Testing Guide

Next Steps

• Set Up MCP Server

• Standard Tools

• Custom Tools

• Testing