MCP Proxy Installation

Complete guide for installing and configuring the Plugged.in MCP Proxy server.

Installation Methods

npm install -g @pluggedin/mcp-proxy

Quick Start

Install Package

npm install -g @pluggedin/mcp-proxy

Create Configuration

mcp-proxy init

Start Server

mcp-proxy start

Verify Installation

curl http://localhost:3000/health

Configuration

Basic Configuration

Create mcp-proxy.config.json:

{
  "port": 3000,
  "host": "0.0.0.0",
  "auth": {
    "type": "apiKey",
    "key": "your-secure-api-key"
  },
  "servers": [
    {
      "name": "github",
      "transport": {
        "type": "streamable",
        "baseUrl": "https://api.github.com/mcp"
      }
    },
    {
      "name": "local",
      "transport": {
        "type": "stdio",
        "command": "node",
        "args": ["./local-server.js"]
      }
    }
  ]
}

Environment Variables

Configure using environment variables:

# Server Configuration
MCP_PROXY_PORT=3000
MCP_PROXY_HOST=0.0.0.0

# Authentication
MCP_PROXY_AUTH_TYPE=apiKey
MCP_PROXY_API_KEY=your-secure-api-key

# Logging
MCP_PROXY_LOG_LEVEL=info
MCP_PROXY_LOG_FORMAT=json

# Performance
MCP_PROXY_MAX_CONNECTIONS=100
MCP_PROXY_TIMEOUT=30000

# Cache
MCP_PROXY_CACHE_ENABLED=true
MCP_PROXY_CACHE_TTL=300000

Advanced Configuration

Full configuration with all options:

{
  "server": {
    "port": 3000,
    "host": "0.0.0.0",
    "cors": {
      "enabled": true,
      "origins": ["https://app.plugged.in"],
      "credentials": true
    }
  },
  "auth": {
    "type": "apiKey",
    "key": "${MCP_PROXY_API_KEY}",
    "header": "X-API-Key"
  },
  "servers": [
    {
      "name": "github",
      "transport": {
        "type": "streamable",
        "baseUrl": "https://api.github.com/mcp",
        "headers": {
          "Authorization": "Bearer ${GITHUB_TOKEN}"
        }
      },
      "retry": {
        "attempts": 3,
        "delay": 1000,
        "backoff": 2
      },
      "timeout": 30000
    }
  ],
  "performance": {
    "connectionPool": {
      "max": 10,
      "min": 2,
      "idle": 60000
    },
    "cache": {
      "enabled": true,
      "ttl": 300000,
      "maxSize": 104857600
    }
  },
  "logging": {
    "level": "info",
    "format": "json",
    "file": "/var/log/mcp-proxy.log"
  },
  "monitoring": {
    "metrics": {
      "enabled": true,
      "port": 9090
    },
    "health": {
      "enabled": true,
      "interval": 30000
    }
  }
}

Docker Deployment

Basic Docker Setup

# Run with default configuration
docker run -p 3000:3000 pluggedin/mcp-proxy:latest

# Run with custom configuration
docker run -p 3000:3000 \
  -v $(pwd)/config.json:/app/config.json \
  -e MCP_PROXY_API_KEY=your-key \
  pluggedin/mcp-proxy:latest

Docker Compose

version: '3.8'

services:
  mcp-proxy:
    image: pluggedin/mcp-proxy:latest
    ports:
      - "3000:3000"
    environment:
      - MCP_PROXY_API_KEY=${API_KEY}
      - MCP_PROXY_LOG_LEVEL=info
    volumes:
      - ./config.json:/app/config.json
      - ./logs:/var/log
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 3s
      retries: 3

Kubernetes Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcp-proxy
spec:
  replicas: 3
  selector:
    matchLabels:
      app: mcp-proxy
  template:
    metadata:
      labels:
        app: mcp-proxy
    spec:
      containers:
      - name: mcp-proxy
        image: pluggedin/mcp-proxy:latest
        ports:
        - containerPort: 3000
        env:
        - name: MCP_PROXY_API_KEY
          valueFrom:
            secretKeyRef:
              name: mcp-proxy-secret
              key: api-key
        livenessProbe:
          httpGet:
            path: /health
            port: 3000
          initialDelaySeconds: 30
          periodSeconds: 30
        resources:
          requests:
            memory: "128Mi"
            cpu: "100m"
          limits:
            memory: "512Mi"
            cpu: "500m"

Server Configuration

STDIO Servers

Configure local command-line MCP servers:

{
  "name": "local-tools",
  "transport": {
    "type": "stdio",
    "command": "python",
    "args": ["mcp_server.py"],
    "env": {
      "PYTHONPATH": "/app/lib"
    },
    "cwd": "/app/servers"
  }
}

Streamable HTTP Servers

Configure HTTP-based MCP servers:

{
  "name": "api-server",
  "transport": {
    "type": "streamable",
    "baseUrl": "https://api.example.com/mcp",
    "headers": {
      "Authorization": "Bearer ${API_TOKEN}",
      "X-Custom-Header": "value"
    }
  },
  "oauth": {
    "enabled": true,
    "provider": "github",
    "clientId": "${GITHUB_CLIENT_ID}",
    "clientSecret": "${GITHUB_CLIENT_SECRET}"
  }
}

SSE Servers (Deprecated)

SSE transport is deprecated. Migrate to Streamable HTTP.

{
  "name": "legacy-sse",
  "transport": {
    "type": "sse",
    "url": "https://legacy.example.com/sse"
  },
  "deprecated": true,
  "migrateTo": "streamable"
}

Integration

Claude Desktop

Add to Claude Desktop configuration:

{
  "mcpServers": {
    "pluggedin-proxy": {
      "command": "mcp-proxy",
      "args": ["start", "--config", "/path/to/config.json"]
    }
  }
}

JavaScript/TypeScript

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

const client = new MCPClient({
  url: 'http://localhost:3000',
  headers: {
    'X-API-Key': 'your-api-key'
  }
});

// List available tools
const tools = await client.listTools();

// Invoke a tool
const result = await client.invokeTool({
  name: 'search_documents',
  parameters: { query: 'MCP proxy' }
});

Python

import requests

# Configure client
api_key = "your-api-key"
base_url = "http://localhost:3000"

headers = {
    "X-API-Key": api_key,
    "Content-Type": "application/json"
}

# List tools
response = requests.get(f"{base_url}/tools", headers=headers)
tools = response.json()

# Invoke tool
payload = {
    "name": "search_documents",
    "parameters": {"query": "MCP proxy"}
}
response = requests.post(f"{base_url}/tools/invoke",
                         json=payload, headers=headers)
result = response.json()

cURL

# List tools
curl -H "X-API-Key: your-api-key" \
     http://localhost:3000/tools

# Invoke tool
curl -X POST \
     -H "X-API-Key: your-api-key" \
     -H "Content-Type: application/json" \
     -d '{"name":"search_documents","parameters":{"query":"MCP"}}' \
     http://localhost:3000/tools/invoke

Monitoring

Health Checks

Monitor proxy health:

# Basic health check
curl http://localhost:3000/health

# Detailed health with server status
curl http://localhost:3000/health?detailed=true

Metrics

Prometheus metrics endpoint:

# Access metrics
curl http://localhost:9090/metrics

# Sample metrics
mcp_proxy_requests_total{method="listTools"} 1234
mcp_proxy_request_duration_seconds{quantile="0.99"} 0.234
mcp_proxy_active_connections 15
mcp_proxy_server_health{server="github"} 1

Logging

Configure logging levels:

{
  "logging": {
    "level": "debug", // trace, debug, info, warn, error
    "format": "json", // json, pretty
    "destinations": [
      {
        "type": "console",
        "level": "info"
      },
      {
        "type": "file",
        "path": "/var/log/mcp-proxy.log",
        "level": "debug",
        "rotate": {
          "maxSize": "10MB",
          "maxFiles": 5
        }
      }
    ]
  }
}

Troubleshooting

Common Issues

Connection Refused

Authentication Failed

Server Connection Failed

High Memory Usage

Debug Mode

Enable debug logging:

# Via environment variable
MCP_PROXY_LOG_LEVEL=debug mcp-proxy start

# Via configuration
{
  "logging": {
    "level": "debug"
  }
}

# Via command line
mcp-proxy start --log-level debug

Performance Tuning

Connection Pool

Optimize connection pooling:

{
  "connectionPool": {
    "max": 20,          // Maximum connections
    "min": 5,           // Minimum idle connections
    "idle": 60000,      // Idle timeout (ms)
    "acquire": 30000,   // Acquire timeout (ms)
    "evict": 10000      // Eviction interval (ms)
  }
}

Caching

Configure cache for better performance:

{
  "cache": {
    "enabled": true,
    "ttl": 300000,      // 5 minutes
    "maxSize": 104857600, // 100MB
    "strategy": "lru",   // lru, lfu, fifo
    "persist": true,     // Persist to disk
    "path": "/var/cache/mcp-proxy"
  }
}

Rate Limiting

Prevent abuse with rate limiting:

{
  "rateLimiting": {
    "enabled": true,
    "window": 60000,    // 1 minute
    "max": 100,         // Max requests per window
    "message": "Too many requests",
    "skipSuccessfulRequests": false,
    "keyGenerator": "ip" // ip, apiKey, custom
  }
}

Security Best Practices

Always follow security best practices in production deployments.

Use Strong API Keys: Generate secure random keys
Enable HTTPS: Use TLS/SSL in production
Restrict CORS: Only allow trusted origins
Rate Limiting: Prevent abuse and DoS
Input Validation: Sanitize all inputs
Audit Logging: Track all operations
Regular Updates: Keep proxy and dependencies updated

Support

For installation help:

Documentation: docs.plugged.in
GitHub Issues: Report issues
GitHub Discussions: Join community
Email Support: api-support@plugged.in

MCP Proxy

​MCP Proxy Installation

​Installation Methods

​Quick Start

​Configuration

​Basic Configuration

​Environment Variables

​Advanced Configuration

​Docker Deployment

​Basic Docker Setup

​Docker Compose

​Kubernetes Deployment

​Server Configuration

​STDIO Servers

​Streamable HTTP Servers

​SSE Servers (Deprecated)

​Integration

​Claude Desktop

​JavaScript/TypeScript

​Python

​cURL

​Monitoring

​Health Checks

​Metrics

​Logging

​Troubleshooting

​Common Issues

​Debug Mode

​Performance Tuning

​Connection Pool

​Caching

​Rate Limiting

​Security Best Practices

​Support

MCP Proxy Installation

Installation Methods

Quick Start

Configuration

Basic Configuration

Environment Variables

Advanced Configuration

Docker Deployment

Basic Docker Setup

Docker Compose

Kubernetes Deployment

Server Configuration

STDIO Servers

Streamable HTTP Servers

SSE Servers (Deprecated)

Integration

Claude Desktop

JavaScript/TypeScript

Python

cURL

Monitoring

Health Checks

Metrics

Logging

Troubleshooting

Common Issues

Debug Mode

Performance Tuning

Connection Pool

Caching

Rate Limiting

Security Best Practices

Support