MCP Proxy Setup - Agentflare

Overview

The MCP Proxy is a hosted service that sits between your AI agents and MCP servers, providing instant observability without requiring code changes. Simply point your MCP client to our proxy endpoint and gain complete visibility into your agent’s behavior.

MCP Proxy Architecture

Request Flow Diagram

How It Works

1. Request Routing

The proxy intelligently routes requests to the appropriate MCP servers:

// Instead of connecting directly to MCP servers
const client = new Client({
  transport: new StdioServerTransport({
    command: "mcp-server",
    args: ["--config", "config.json"]
  })
});

// Connect through Agentflare proxy
const client = new Client({
  transport: new HTTPTransport({
    baseUrl: "https://<your-workspace>.agentflare.com/proxy",
    headers: {
      "Authorization": `Bearer ${process.env.API_JWT_SECRET}`,
      "X-Target-Server": "<your-mcp-server>"
    }
  })
});

2. Transparent Observability

Every request and response is captured automatically:

Request Capture

Complete request data including parameters and context

Response Logging

Full response data with timing and status

Error Tracking

Detailed error information and stack traces

Performance Metrics

Response times, throughput, and resource usage

3. Multi-Tenant Architecture

Secure isolation for multiple workspaces:

Workspace Isolation
Security

// Each workspace gets its own isolated environment
const workspaceConfig = {
  workspace_id: "ws_abc123",
  subdomain: "<your-company>",
  custom_domain: "mcp.yourcompany.com",
  servers: [
    {
      name: "search-server",
      endpoint: "https://search.yourcompany.com",
      auth: "bearer_token"
    },
    {
      name: "email-server", 
      endpoint: "https://email.yourcompany.com",
      auth: "api_key"
    }
  ]
};

Quick Setup

1. Get Your Proxy URL

From your Agentflare dashboard:

Navigate to Proxy Settings

Go to Dashboard → Settings → Proxy Configuration

Copy Proxy URL

Copy your unique proxy URL: https://<your-workspace>.agentflare.com/proxy

Generate API Key

Create an API key for proxy authentication

Configure Servers

Add your MCP servers to the proxy configuration

2. Update Your Client

Modify your MCP client to use the proxy:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { HTTPTransport } from "@modelcontextprotocol/sdk/client/http.js";

const client = new Client({
  transport: new HTTPTransport({
    baseUrl: "https://proxy.agentflare.com/<your-workspace>/<your-server-slug>",
    headers: {
      "Authorization": `Bearer ${process.env.AGENTFLARE_API_KEY}`
    }
  })
});

Server Configuration

1. Add MCP Servers

Configure your MCP servers in the proxy:

HTTP/HTTPS Servers

{
  "name": "search-server",
  "type": "http",
  "endpoint": "https://search.yourcompany.com/mcp",
  "authentication": {
    "type": "bearer",
    "token": "<<your-server>-token>"
  },
  "timeout": 30000,
  "retry": {
    "enabled": true,
    "max_attempts": 3,
    "backoff": "exponential"
  }
}

WebSocket Servers

{
  "name": "realtime-server",
  "type": "websocket",
  "endpoint": "wss://realtime.yourcompany.com/mcp",
  "authentication": {
    "type": "oauth2",
    "client_id": "<your-client-id>",
    "client_secret": "<your-client-secret>"
  },
  "heartbeat": {
    "enabled": true,
    "interval": 30000
  }
}

Stdio Servers

{
  "name": "local-server",
  "type": "stdio",
  "command": "/usr/local/bin/mcp-server",
  "args": ["--config", "/etc/mcp/config.json"],
  "env": {
    "MCP_SERVER_TOKEN": "<your-token>",
    "LOG_LEVEL": "info"
  },
  "working_directory": "/app"
}

2. Load Balancing

Distribute requests across multiple server instances:

{
  "name": "search-cluster",
  "type": "load_balanced",
  "strategy": "round_robin",
  "servers": [
    {
      "endpoint": "https://search1.yourcompany.com/mcp",
      "weight": 1
    },
    {
      "endpoint": "https://search2.yourcompany.com/mcp", 
      "weight": 1
    },
    {
      "endpoint": "https://search3.yourcompany.com/mcp",
      "weight": 2
    }
  ]
}

Custom Domains

1. Domain Setup

Use your own domain for the proxy:

Choose Domain

Select a subdomain like mcp.yourcompany.com

Configure DNS

Add a CNAME record pointing to our proxy

Upload SSL Certificate

Provide your SSL certificate or use our automatic SSL

Verify Setup

Test the custom domain configuration

2. SSL Configuration

Secure your proxy with SSL/TLS:

Automatic SSL
Custom Certificate

{
  "domain": "mcp.yourcompany.com",
  "ssl": {
    "type": "automatic",
    "provider": "letsencrypt",
    "auto_renew": true
  }
}

Advanced Features

1. Request Transformation

Modify requests before forwarding:

const transformationRules = {
  headers: {
    add: {
      "X-Client-ID": "agentflare-proxy",
      "X-Request-ID": "{{ request_id }}"
    },
    remove: ["X-Internal-Token"],
    transform: {
      "Authorization": "Bearer {{ server_token }}"
    }
  },
  body: {
    add_fields: {
      "proxy_timestamp": "{{ timestamp }}",
      "workspace_id": "{{ workspace_id }}"
    }
  }
};

2. Caching Strategy

Improve performance with intelligent caching:

Response Caching

{
  "caching": {
    "enabled": true,
    "strategy": "adaptive",
    "rules": [
      {
        "path": "/tools/search",
        "method": "POST",
        "ttl": 300,
        "cache_key": "body.query + body.filters"
      },
      {
        "path": "/tools/static-data",
        "method": "GET",
        "ttl": 3600,
        "cache_key": "path + query_params"
      }
    ]
  }
}

Cache Invalidation

{
  "cache_invalidation": {
    "strategies": [
      {
        "trigger": "time_based",
        "ttl": 1800
      },
      {
        "trigger": "event_based",
        "events": ["data_update", "schema_change"]
      },
      {
        "trigger": "manual",
        "api_endpoint": "/cache/invalidate"
      }
    ]
  }
}

3. Rate Limiting

Protect your servers from overload:

Global Limits
Per-Tool Limits

{
  "rate_limiting": {
    "global": {
      "requests_per_minute": 10000,
      "burst_limit": 100,
      "window_size": 60
    },
    "per_workspace": {
      "requests_per_minute": 1000,
      "burst_limit": 50
    }
  }
}

Monitoring & Debugging

1. Request Tracing

Track requests through the proxy:

const traceConfig = {
  enabled: true,
  sample_rate: 1.0, // 100% sampling
  include: {
    headers: true,
    body: true,
    response: true,
    timing: true,
    errors: true
  },
  export: {
    jaeger: {
      endpoint: "http://jaeger:14268/api/traces"
    },
    datadog: {
      api_key: "<your-datadog-key>"
    }
  }
};

2. Health Checks

Monitor server health through the proxy:

Automated Health Checks

{
  "health_checks": {
    "enabled": true,
    "interval": 30,
    "timeout": 5,
    "endpoints": [
      {
        "server": "search-server",
        "path": "/health",
        "expected_status": 200
      },
      {
        "server": "email-server",
        "path": "/ping",
        "expected_body": "pong"
      }
    ]
  }
}

Failure Handling

{
  "failure_handling": {
    "unhealthy_threshold": 3,
    "recovery_threshold": 2,
    "actions": {
      "on_failure": ["remove_from_rotation", "alert_ops"],
      "on_recovery": ["add_to_rotation", "notify_ops"]
    }
  }
}

Security Best Practices

1. Authentication & Authorization

Always use strong authentication and regularly rotate API keys.

API Key Management

Use separate API keys for different environments and applications

Regular Rotation

Rotate API keys monthly or after any security incidents

Least Privilege

Grant only the minimum permissions required for each use case

Monitoring

Monitor API key usage for suspicious activity

2. Network Security

IP Whitelisting

Restrict access to specific IP addresses

VPN Integration

Route traffic through your corporate VPN

Private Networks

Use private networking for sensitive connections

Encryption

Encrypt all data in transit and at rest

Troubleshooting

1. Common Issues

Connection Timeouts

Symptoms: Requests timing out or taking too longSolutions:

Increase timeout values in proxy configuration
Check network connectivity between proxy and servers
Verify server performance and capacity
Review server logs for bottlenecks

Authentication Failures

Symptoms: 401 or 403 errorsSolutions:

Verify API key is correct and active
Check server authentication configuration
Ensure proper headers are being sent
Review authentication logs

Rate Limiting

Symptoms: 429 Too Many Requests errorsSolutions:

Review rate limiting configuration
Implement exponential backoff in clients
Distribute load across multiple servers
Consider upgrading rate limits

2. Debug Tools

# Test proxy connectivity
curl -H "Authorization: Bearer <your-api-key>" \
     -H "X-Target-Server: <your-server>" \
     https://<your-workspace>.agentflare.com/proxy/health

# Test specific tool
curl -X POST \
     -H "Authorization: Bearer <your-api-key>" \
     -H "X-Target-Server: <your-server>" \
     -H "Content-Type: application/json" \
     -d '{"method": "tools/list"}' \
     https://<your-workspace>.agentflare.com/proxy/rpc

Next Steps

Custom Domains

Set up your own domain for the proxy

Authentication

Configure secure authentication

OTEL Integration

Export observability data

Performance Analytics

Monitor proxy performance

The MCP Proxy provides zero-configuration observability. You can start getting insights immediately without changing your existing code.

Getting Started

Observability

Analytics & Monitoring

Integration

API Reference

Resources

Support

​Overview

​MCP Proxy Architecture

​Request Flow Diagram

​How It Works

​1. Request Routing

​2. Transparent Observability

Request Capture

Response Logging

Error Tracking

Performance Metrics

​3. Multi-Tenant Architecture

​Quick Setup

​1. Get Your Proxy URL

​2. Update Your Client

​Server Configuration

​1. Add MCP Servers

​2. Load Balancing

​Custom Domains

​1. Domain Setup

​2. SSL Configuration

​Advanced Features

​1. Request Transformation

​2. Caching Strategy

​3. Rate Limiting

​Monitoring & Debugging

​1. Request Tracing

​2. Health Checks

​Security Best Practices

​1. Authentication & Authorization

​2. Network Security

IP Whitelisting

VPN Integration

Private Networks

Encryption

​Troubleshooting

​1. Common Issues

​2. Debug Tools

​Next Steps

Custom Domains

Authentication

OTEL Integration

Performance Analytics

Overview

MCP Proxy Architecture

Request Flow Diagram

How It Works

1. Request Routing

2. Transparent Observability

3. Multi-Tenant Architecture

Quick Setup

1. Get Your Proxy URL

2. Update Your Client

Server Configuration

1. Add MCP Servers

2. Load Balancing

Custom Domains

1. Domain Setup

2. SSL Configuration

Advanced Features

1. Request Transformation

2. Caching Strategy

3. Rate Limiting

Monitoring & Debugging

1. Request Tracing

2. Health Checks

Security Best Practices

1. Authentication & Authorization

2. Network Security

Troubleshooting

1. Common Issues

2. Debug Tools

Next Steps