IDE & AI Tool Setup

Connect AI tools to your MCP Gateway. Includes header forwarding for authentication and tracing.

This guide covers how to connect popular AI tools to your Cosmo Router MCP server and configure header forwarding for authentication, tracing, and custom headers.

Header Forwarding

Available since Router 0.260.0

The MCP server forwards most client headers to the Router - including authorization, custom, and tracing headers - but skips hop-by-hop and content negotiation headers (defined in headers.SkippedHeaders). This allows you to:

• Leverage all authentication and authorization capabilities of your Cosmo Router
• Pass custom headers for tracing, debugging, or application-specific purposes
• Maintain consistent security and observability across all API consumers

Headers are forwarded through the chain: MCP Client -> MCP Server -> Router -> Subgraphs. The router’s header forwarding rules determine what ultimately reaches your subgraphs.

IDE Setup Guides

Cursor

Requires Cursor v0.48.0+ for Streamable HTTP support.

Go to Settings > Tools & Integrations > MCP Servers and add the following to the mcp.json file:

{
  "mcpServers": {
    "my-graph": {
      "url": "http://localhost:5025/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY",
        "X-Trace-Id": "cursor-session-123",
        "X-Client": "cursor"
      }
    }
  }
}

All headers fields are optional - include only what your setup requires.

Claude Desktop

Requires the latest version of Claude Desktop. Go to Settings > Developer and click on Edit Config. Add the following to the claude_desktop_config.json file:

{
  "mcpServers": {
    "my-graph": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:5025/mcp"]
    }
  }
}

After saving, restart Claude Desktop for changes to take effect.

Windsurf

Windsurf supports Streamable HTTP servers with a serverUrl field:

{
  "mcpServers": {
    "my-graph": {
      "serverUrl": "http://localhost:5025/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY",
        "X-Trace-Id": "windsurf-session-456",
        "X-Client": "windsurf"
      }
    }
  }
}

VS Code

Click View > Command Palette > MCP: Add Server and use the URL http://localhost:5025/mcp to complete the configuration.

For more information, see the VS Code MCP Servers documentation.

Other MCP-compatible Tools

Other tools and AI models that support the MCP protocol typically provide similar ways to configure the server URL and authentication headers. Check the documentation for your specific AI tool for the exact configuration syntax.

Common Header Patterns

Authentication & Authorization

Pass authorization tokens to secure your GraphQL operations:

{
  "headers": {
    "Authorization": "Bearer YOUR_API_KEY"
  }
}

Tracing

Include trace IDs for request correlation and debugging:

{
  "headers": {
    "X-Trace-Id": "trace-123",
    "X-Request-Id": "req-456"
  }
}

Custom Headers

Pass application-specific headers for business logic:

{
  "headers": {
    "X-Tenant-Id": "tenant-abc",
    "X-Feature-Flag": "new-feature-enabled"
  }
}