# Setting Up MCP Server

Complete guide to setting up an AIDP MCP (Model Context Protocol) server.

## What is MCP?

The Model Context Protocol (MCP) is an open standard that enables AI assistants to securely connect to external data sources and tools. AIDP provides native MCP support for seamless integration with AI platforms like Claude, ChatGPT, and others.

***

## Prerequisites

* Node.js 18+ or Python 3.8+
* AIDP API key from [platform.aidp.dev](https://platform.aidp.dev)
* Basic understanding of REST APIs
* (Optional) Docker for containerized deployment

***

## Installation

### Option 1: Using npm (Node.js)

```bash
npm install -g @aidp/mcp-server
```

### Option 2: Using pip (Python)

```bash
pip install aidp-mcp-server
```

### Option 3: Using Docker

```bash
docker pull aidp/mcp-server:latest
```

***

## Quick Start

### 1. Initialize Configuration

Create a configuration file:

```bash
aidp-mcp init
```

This creates `mcp-config.yml`:

```yaml
server:
  port: 3000
  host: 0.0.0.0
  name: 'AIDP MCP Server'

aidp:
  apiKey: ${AIDP_API_KEY}
  environment: production
  baseUrl: https://api.aidp.dev/v1

tools:
  enabled:
    - search_businesses
    - get_business
    - get_business_hours
    - get_business_services
    - get_business_reviews

security:
  cors:
    enabled: true
    origins:
      - https://claude.ai
      - https://chat.openai.com
  rateLimit:
    enabled: true
    maxRequests: 100
    windowMs: 60000
```

### 2. Set Environment Variables

```bash
export AIDP_API_KEY="your-api-key-here"
```

Or create a `.env` file:

```env
AIDP_API_KEY=your-api-key-here
MCP_PORT=3000
MCP_HOST=0.0.0.0
```

### 3. Start the Server

```bash
aidp-mcp start
```

Or with custom config:

```bash
aidp-mcp start --config ./custom-config.yml
```

**Expected Output**:

```
✓ AIDP MCP Server started
✓ Listening on http://0.0.0.0:3000
✓ Connected to AIDP API
✓ 5 tools registered
✓ Ready to accept connections
```

***

## Configuration Options

### Server Configuration

```yaml
server:
  port: 3000 # Server port
  host: 0.0.0.0 # Bind address
  name: 'My MCP Server' # Server name
  version: '1.0.0' # Server version
  timeout: 30000 # Request timeout (ms)
```

### AIDP Configuration

```yaml
aidp:
  apiKey: ${AIDP_API_KEY} # API key (use env var)
  environment: production # 'production' or 'sandbox'
  baseUrl: https://api.aidp.dev/v1 # API base URL
  timeout: 30000 # API timeout (ms)
  retries: 3 # Retry attempts
```

### Tool Configuration

```yaml
tools:
  enabled:
    - search_businesses
    - get_business
    - get_business_hours

  # Custom tool parameters
  search_businesses:
    defaultLimit: 10
    maxLimit: 50

  get_business:
    includeReviews: true
    includeAnalytics: false
```

### Security Configuration

```yaml
security:
  cors:
    enabled: true
    origins:
      - https://claude.ai
      - https://chat.openai.com
    methods:
      - GET
      - POST
    credentials: true

  rateLimit:
    enabled: true
    maxRequests: 100
    windowMs: 60000

  authentication:
    required: true
    type: bearer
```

***

## Docker Deployment

### Using Docker Compose

Create `docker-compose.yml`:

```yaml
version: '3.8'

services:
  aidp-mcp:
    image: aidp/mcp-server:latest
    ports:
      - '3000:3000'
    environment:
      - AIDP_API_KEY=${AIDP_API_KEY}
      - MCP_PORT=3000
      - MCP_HOST=0.0.0.0
    volumes:
      - ./mcp-config.yml:/app/config.yml
    restart: unless-stopped
    healthcheck:
      test: ['CMD', 'curl', '-f', 'http://localhost:3000/health']
      interval: 30s
      timeout: 10s
      retries: 3
```

Start the server:

```bash
docker-compose up -d
```

***

## Verification

### 1. Check Server Health

```bash
curl http://localhost:3000/health
```

**Expected Response**:

```json
{
  "status": "healthy",
  "version": "1.0.0",
  "uptime": 123.45,
  "aidp": {
    "connected": true,
    "apiVersion": "v1"
  }
}
```

### 2. List Available Tools

```bash
curl http://localhost:3000/mcp/tools
```

**Expected Response**:

```json
{
  "tools": [
    {
      "name": "search_businesses",
      "description": "Search for businesses using natural language",
      "parameters": {...}
    },
    {
      "name": "get_business",
      "description": "Get detailed business information",
      "parameters": {...}
    }
  ]
}
```

### 3. Test a Tool

```bash
curl -X POST http://localhost:3000/mcp/call \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "search_businesses",
    "parameters": {
      "query": "coffee shops",
      "location": {"lat": 45.5231, "lon": -122.6765}
    }
  }'
```

***

## Production Deployment

### Using PM2 (Node.js)

```bash
# Install PM2
npm install -g pm2

# Start server with PM2
pm2 start aidp-mcp --name "aidp-mcp-server"

# Save PM2 configuration
pm2 save

# Setup auto-restart on reboot
pm2 startup
```

### Using systemd (Linux)

Create `/etc/systemd/system/aidp-mcp.service`:

```ini
[Unit]
Description=AIDP MCP Server
After=network.target

[Service]
Type=simple
User=aidp
WorkingDirectory=/opt/aidp-mcp
Environment="AIDP_API_KEY=your-api-key"
ExecStart=/usr/local/bin/aidp-mcp start
Restart=always

[Install]
WantedBy=multi-user.target
```

Enable and start:

```bash
sudo systemctl enable aidp-mcp
sudo systemctl start aidp-mcp
sudo systemctl status aidp-mcp
```

***

## Monitoring

### Logs

```bash
# View logs
aidp-mcp logs

# Follow logs
aidp-mcp logs --follow

# View last 100 lines
aidp-mcp logs --tail 100
```

### Metrics

Access metrics endpoint:

```bash
curl http://localhost:3000/metrics
```

**Response**:

```json
{
  "uptime": 3600,
  "requests": {
    "total": 1234,
    "successful": 1200,
    "failed": 34
  },
  "tools": {
    "search_businesses": 800,
    "get_business": 400
  },
  "performance": {
    "avgResponseTime": 150,
    "p95ResponseTime": 300
  }
}
```

***

## Troubleshooting

### Server Won't Start

**Issue**: `Error: AIDP API key not found`

**Solution**:

```bash
export AIDP_API_KEY="your-api-key"
# or
echo "AIDP_API_KEY=your-api-key" > .env
```

### Connection Refused

**Issue**: `ECONNREFUSED` when calling tools

**Solution**: Check if server is running:

```bash
curl http://localhost:3000/health
```

### CORS Errors

**Issue**: Browser shows CORS errors

**Solution**: Add your domain to CORS origins:

```yaml
security:
  cors:
    origins:
      - https://your-domain.com
```

***

## Next Steps

* [Configure Standard Tools →](https://amistan.gitbook.io/aidp-docs/for-developers/mcp-integration/tools)
* [Create Custom Tools →](https://amistan.gitbook.io/aidp-docs/for-developers/mcp-integration/custom-tools)
* [Testing Your MCP Server →](https://amistan.gitbook.io/aidp-docs/for-developers/mcp-integration/testing)

***

## Support

* 📧 Email: <mcp@aidp.dev>
* 💬 GitHub Discussions: [github.com/aidp/platform/discussions](https://github.com/aidp/platform/discussions)
* 📚 Documentation: [docs.aidp.dev/mcp](https://docs.aidp.dev/mcp)