## Header Forwarding

Available since Router [0.260.0](https://github.com/wundergraph/cosmo/releases/tag/router%400.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`](https://github.com/wundergraph/cosmo/blob/main/router/internal/headers/headers.go)). 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](https://cosmo-docs.wundergraph.com/router/proxy-capabilities/subgraph-request-header-operations) 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](https://code.visualstudio.com/docs/copilot/chat/mcp-servers).

### 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"
  }
}
```