Feature Request: Support Custom Headers for MCP Servers in OpenAI Realtime API

[mattlgroff]

Problem Description

The OpenAI Realtime API's MCP (Model Context Protocol) integration currently only supports a single authorization field for authentication with remote MCP servers. This limits integration with servers that require
custom headers such as X-API-KEY, multiple authentication headers, or other custom headers for routing, versioning, or identification.

Current Limitation

The current MCP configuration only allows:

{
  "type": "mcp",
  "server_url": "https://example-mcp-server.com/mcp",
  "authorization": "Bearer token",  // Only supports Authorization header
  "server_label": "example",
  "require_approval": "never"
}

This translates to a single header:

Authorization: Bearer token

Real-World Authentication Scenarios Not Supported

Many MCP servers and APIs use different authentication patterns:

1. API Key Headers:
   X-API-KEY: your-api-key-here

2. Multiple Auth Headers:
   X-Client-ID: client-123
   X-Client-Secret: secret-456

3. Custom Headers for Routing/Versioning:
   X-API-Version: 2024-11-05
   X-Tenant-ID: tenant-123
   X-Environment: production

4. Non-Bearer Authorization:
   Authorization: ApiKey your-key-here
   Authorization: Basic base64encoded

Feature Request

Add support for custom headers in MCP server configuration. This would allow developers to specify any headers required by their MCP servers.

Proposed Implementation

Option 1: Headers Object (Recommended)

{
  "type": "mcp",
  "server_url": "https://example-mcp-server.com/mcp",
  "server_label": "example",
  "headers": {
    "X-API-KEY": "your-api-key-here",
    "X-Client-ID": "client-123",
    "X-API-Version": "2024-11-05"
  },
  "require_approval": "never"
}

Option 2: Headers Array

{
  "type": "mcp",
  "server_url": "https://example-mcp-server.com/mcp",
  "server_label": "example",
  "headers": [
    {"name": "X-API-KEY", "value": "your-api-key-here"},
    {"name": "X-Client-ID", "value": "client-123"}
  ],
  "require_approval": "never"
}

Option 3: Keep Authorization + Add Custom Headers

{
  "type": "mcp",
  "server_url": "https://example-mcp-server.com/mcp",
  "server_label": "example",
  "authorization": "Bearer token",  // Backward compatible
  "custom_headers": {  // Additional headers
    "X-API-KEY": "additional-key",
    "X-Tenant-ID": "tenant-123"
  },
  "require_approval": "never"
}

Example Use Case from Our Implementation

Here's how we currently have to work around this limitation by hardcoding our API key:

For example an MCP Server might expect:

X-API-KEY: your-api-key-here

But we're forced to use:

Authorization: your-api-key-here

This requires specifically supporting only Authorization headers with Bearer tokens on your MCP Server, and if you're using someone else's and they don't support that exact setup you can't use the Realtime API with that MCP Server.

Benefits of This Feature

1. Compatibility: Support MCP servers with existing authentication schemes
2. Security: Allow proper multi-factor authentication with multiple headers
3. Flexibility: Support enterprise scenarios with custom routing/tenant headers
4. Standards Compliance: Many APIs use X-API-KEY as the standard for API key authentication
5. No Server Modifications: Connect to existing MCP servers without modifications

Impact

This is a backward-compatible enhancement that would:

• Keep existing authorization field for simple Bearer token cases
• Add optional headers field for advanced use cases
• Significantly expand the number of MCP servers that can integrate with Realtime API

Request Summary

Please add support for custom headers in MCP server configuration for the Realtime API. This would remove a significant limitation and allow integration with MCP servers that use standard API authentication
patterns beyond Bearer tokens.