MCP Client Setup

Guide to integrating AIDP using the Model Context Protocol (MCP).

What is MCP?

The Model Context Protocol (MCP) is an open standard for connecting AI assistants to external data sources and tools. AIDP provides native MCP support for seamless integration.

---

Installation

TypeScript/JavaScript

npm install @modelcontextprotocol/sdk @aidp/mcp-client

Python

pip install mcp-sdk aidp-mcp-client

---

Quick Start

TypeScript

import { MCPClient } from '@modelcontextprotocol/sdk';
import { AIDPMCPServer } from '@aidp/mcp-client';

// Initialize MCP client
const client = new MCPClient({
  serverUrl: 'https://mcp.aidp.dev',
  apiKey: process.env.AIDP_API_KEY,
});

// Connect to AIDP MCP server
await client.connect();

// Search for businesses
const results = await client.callTool('search_businesses', {
  query: 'coffee shops',
  location: { lat: 45.5231, lon: -122.6765 },
});

console.log(results);

Python

from mcp import MCPClient
from aidp_mcp import AIDPMCPServer

# Initialize MCP client
client = MCPClient(
    server_url='https://mcp.aidp.dev',
    api_key=os.environ['AIDP_API_KEY']
)

# Connect
await client.connect()

# Search for businesses
results = await client.call_tool('search_businesses', {
    'query': 'coffee shops',
    'location': {'lat': 45.5231, 'lon': -122.6765}
})

print(results)

---

Available MCP Tools

search_businesses

Search for businesses using natural language.

Parameters:

{
  "query": "string (required)",
  "location": {
    "lat": "number (required)",
    "lon": "number (required)",
    "distance": "string (optional, default: '10km')"
  },
  "category": "string (optional)",
  "limit": "number (optional, default: 10)"
}

Returns:

{
  "businesses": [...],
  "total": 42,
  "response": "AI-generated response text"
}

---

get_business

Get detailed information about a specific business.

Parameters:

{
  "businessId": "string (required)"
}

Returns:

{
  "id": "biz_abc123",
  "name": "Artisan Coffee Roasters",
  "category": "restaurants",
  ...
}

---

get_business_hours

Check if a business is currently open.

Parameters:

{
  "businessId": "string (required)",
  "datetime": "string (optional, ISO 8601)"
}

Returns:

{
  "isOpen": true,
  "currentHours": { "open": "07:00", "close": "18:00" },
  "nextChange": "2024-12-12T18:00:00Z"
}

---

get_business_services

Get services offered by a business.

Parameters:

{
  "businessId": "string (required)"
}

Returns:

{
  "services": [
    {
      "name": "Espresso Drinks",
      "description": "...",
      "pricing": {...}
    }
  ]
}

---

Configuration

Server Configuration

const client = new MCPClient({
  serverUrl: 'https://mcp.aidp.dev',
  apiKey: process.env.AIDP_API_KEY,
  timeout: 30000,
  retries: 3,
  headers: {
    'X-Platform': 'my-ai-platform',
  },
});

Tool Discovery

List available tools:

const tools = await client.listTools();

tools.forEach((tool) => {
  console.log(`Tool: ${tool.name}`);
  console.log(`Description: ${tool.description}`);
  console.log(`Parameters:`, tool.parameters);
});

---

Advanced Usage

Custom Tool Handlers

client.onToolCall('search_businesses', async (params) => {
  // Pre-process parameters
  const enhancedParams = {
    ...params,
    sessionId: getCurrentSessionId(),
  };

  // Call tool
  const results = await client.callTool('search_businesses', enhancedParams);

  // Post-process results
  return formatResults(results);
});

Error Handling

try {
  const results = await client.callTool('search_businesses', params);
} catch (error) {
  if (error.code === 'TOOL_NOT_FOUND') {
    console.error('Tool not available');
  } else if (error.code === 'INVALID_PARAMETERS') {
    console.error('Invalid parameters:', error.details);
  } else {
    console.error('Tool call failed:', error.message);
  }
}

---

Self-Hosting MCP Server

Run your own AIDP MCP server:

# Using Docker
docker run -p 3000:3000 \
  -e AIDP_API_KEY=your-api-key \
  aidp/mcp-server:latest

# Using npm
npm install -g @aidp/mcp-server
aidp-mcp-server --port 3000 --api-key your-api-key

Configuration:

# config.yml
server:
  port: 3000
  host: 0.0.0.0

aidp:
  apiKey: ${AIDP_API_KEY}
  environment: production

tools:
  - search_businesses
  - get_business
  - get_business_hours
  - get_business_services

---

Testing

Test MCP Connection

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

async function testConnection() {
  const client = new MCPClient({
    serverUrl: 'https://mcp.aidp.dev',
    apiKey: process.env.AIDP_TEST_API_KEY,
  });

  try {
    await client.connect();
    console.log('✅ Connected to AIDP MCP server');

    const tools = await client.listTools();
    console.log(`✅ Found ${tools.length} tools`);

    const results = await client.callTool('search_businesses', {
      query: 'test',
      location: { lat: 45.5231, lon: -122.6765 },
    });
    console.log('✅ Search test successful');
  } catch (error) {
    console.error('❌ Test failed:', error);
  } finally {
    await client.disconnect();
  }
}

testConnection();

---

Best Practices

1. Connection Pooling

Reuse MCP connections:

class MCPConnectionPool {
  private connections: Map<string, MCPClient> = new Map();

  async getConnection(apiKey: string): Promise<MCPClient> {
    if (!this.connections.has(apiKey)) {
      const client = new MCPClient({
        serverUrl: 'https://mcp.aidp.dev',
        apiKey,
      });
      await client.connect();
      this.connections.set(apiKey, client);
    }
    return this.connections.get(apiKey)!;
  }
}

2. Graceful Shutdown

Clean up connections:

process.on('SIGTERM', async () => {
  await client.disconnect();
  process.exit(0);
});

3. Monitoring

Monitor MCP health:

setInterval(async () => {
  try {
    await client.ping();
  } catch (error) {
    console.error('MCP server unhealthy:', error);
    await client.reconnect();
  }
}, 30000);

---

Support

• 📧 Email: [e-mail]

• 💬 GitHub Discussions: github.com/aidp/platform/discussions

• 📚 MCP Spec: modelcontextprotocol.io

---

Next: Discovery & Search →