Pre-submission Checklist

• I have verified that this discussion would not be more appropriate as an issue in a specific repository
• I have searched existing discussions to avoid duplicates

Discussion Topic

Proposal: Add Client-Level Request Identifiers for Distributed Tracing and Multi-Tenancy

Pre-submission Checklist

• I have searched for existing discussions and issues to ensure this isn't a duplicate
• This suggestion affects the core MCP protocol specification rather than a specific server implementation
• I have considered whether this belongs in the main MCP forum rather than a specific repository

Summary

Add support for client-level identifier configuration that automatically applies to all MCP tool calls, with optional per-request additional identifiers. MCP servers would automatically forward these identifiers as HTTP headers to downstream APIs, enabling end-to-end tracing and multi-tenant context passing without requiring server-side code changes.

Scope

• Protocol Specification
• SDK Features
• Documentation
• Developer Experience
• Community Resources
• Tooling

Abstract

The current MCP protocol lacks a standardized mechanism for passing request-scoped metadata (trace IDs, user context, tenant IDs) from clients through servers to downstream APIs. This proposal introduces an optional identifiers field for client configuration and tool requests, with automatic HTTP header forwarding by MCP servers. The feature is backward-compatible and provides clean separation between business logic and infrastructure concerns.

Motivation

Current Problem

• No observability: Cannot trace requests end-to-end across MCP boundaries
• Multi-tenancy gaps: No way to pass tenant/user context to downstream services
• Compliance issues: Cannot maintain audit trails through MCP servers
• Complex workarounds: Developers resort to URL manipulation, environment variable injection, or custom proxies

Use Cases

1. Distributed Tracing: Pass trace IDs through MCP to downstream services
2. Multi-tenant SaaS: Forward tenant and user context for data isolation
3. Audit Logging: Maintain compliance trails across service boundaries
4. Request Correlation: Track requests across multiple MCP servers
5. Rate Limiting: Provide user/customer context for per-entity limits

Proposal Details

Client-Level Configuration

Configure identifiers when creating MCP clients - applies to ALL tool calls:

const client = new Client({
  name: "my-app",
  version: "1.0.0",
  identifiers: {
    "trace-id": "abc123",
    "tenant-id": "tenant789", 
    "user-id": "user456"
  }
});

Per-Request Additional Identifiers

Optional extra identifiers for specific tool calls:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "api_tool",
    "arguments": { "data": "value" },
    "identifiers": {
      "request-id": "req-001",
      "operation": "create-ticket"
    }
  },
  "id": 1
}

Automatic Header Forwarding

MCP servers automatically forward identifiers as HTTP headers:

POST /api/endpoint HTTP/1.1
X-MCP-Trace-Id: abc123
X-MCP-Tenant-Id: tenant789
X-MCP-User-Id: user456
X-MCP-Request-Id: req-001
X-MCP-Operation: create-ticket
Content-Type: application/json

{"data": "value"}

Client Configuration

MCP clients can configure identifier forwarding per server:

{
  "mcpServers": {
    "time": {
      "command": "python",
      "args": ["-m", "mcp_server_time"],
      "env": {},
      "identifier_forwarding": {
        "enabled": true,
        "header_prefix": "X-MCP-",
        "allowed_keys": ["trace-id", "user-id", "tenant-id"],
        "max_identifiers": 20,
        "max_value_length": 256
      }
    }
  }
}

Implementation Work Required

Protocol Changes

• Add optional identifiers field to CallToolRequest schema
• Add identifier_forwarding configuration to client connection specifications
• Update MCP protocol documentation with new fields and behavior

SDK Implementation

• TypeScript SDK: Add identifier handling to Client and McpServer classes
• Python SDK: Implement identifier forwarding in client and server modules
• Other SDKs: Follow established patterns for consistency
• Automatic HTTP header injection for servers making outbound requests

Validation

• Test backward compatibility with existing MCP servers
• Validate identifier forwarding with real HTTP services
• Performance testing with multiple identifiers
• Security validation of input sanitization and limits

Backward Compatibility

• Existing clients: Work unchanged (no identifiers sent)
• Existing servers: Ignore unknown identifiers field
• New functionality: Opt-in via configuration
• Zero breaking changes: No impact on current implementations

Security Considerations

• Disabled by default: Must be explicitly enabled via configuration
• Input validation: Servers validate and sanitize identifier values
• Whitelisting: Configurable allowed identifier keys
• Size limits: Prevent abuse with configurable maximums
• Header collision prevention: MCP-specific prefix avoids conflicts
• No sensitive data: Identifiers for tracking, not authentication

Future Work

This proposal focuses on the core identifier forwarding mechanism. Future enhancements could include:

• Integration with OpenTelemetry standards
• Enhanced debugging capabilities in MCP Inspector
• Standardized identifier naming conventions
• Support for structured identifier formats (JSON, etc.)

Questions for Discussion

1. Should the default header prefix be X-MCP- or something else?
2. Are the proposed configuration options sufficient for most use cases?
3. Should there be standardized identifier names (e.g., trace-id, span-id)?
4. How should identifier conflicts be handled when client and request identifiers have the same key?

Reference Implementation

To demonstrate the feasibility of this proposal, here's how identifier forwarding could be implemented in the MCP SDKs:

TypeScript SDK Changes

Client-side identifier configuration:

export interface ClientOptions {
  name: string;
  version: string;
  identifiers?: Record<string, string>; // New field
}

export class Client {
  private clientIdentifiers: Record<string, string>;
  
  constructor(options: ClientOptions) {
    this.clientIdentifiers = options.identifiers || {};
  }
  
  async callTool(params: CallToolParams & { identifiers?: Record<string, string> }) {
    const mergedIdentifiers = {
      ...this.clientIdentifiers,
      ...params.identifiers
    };
    
    return this.request({
      method: 'tools/call',
      params: {
        ...params,
        identifiers: mergedIdentifiers
      }
    });
  }
}

Server-side automatic forwarding:

export class McpServer {
  private identifierConfig: IdentifierConfig;
  
  constructor(clientConfig?: any) {
    const config = clientConfig?.identifier_forwarding || {};
    this.identifierConfig = {
      enabled: config.enabled || false,
      headerPrefix: config.header_prefix || 'X-MCP-',
      allowedKeys: config.allowed_keys || null,
      maxIdentifiers: config.max_identifiers || 20,
      maxValueLength: config.max_value_length || 256
    };
  }
  
  private forwardIdentifiersAsHeaders(
    identifiers: Record<string, string>, 
    requestOptions: any
  ) {
    if (!this.identifierConfig.enabled) return;
    
    const headers = requestOptions.headers || {};
    let identifierCount = 0;
    
    Object.entries(identifiers).forEach(([key, value]) => {
      if (identifierCount >= this.identifierConfig.maxIdentifiers) return;
      if (value.length > this.identifierConfig.maxValueLength) return;
      
      if (this.identifierConfig.allowedKeys && 
          !this.identifierConfig.allowedKeys.includes(key)) {
        return;
      }
      
      const headerName = `${this.identifierConfig.headerPrefix}${
        key.split(/[-_]/).map(part => 
          part.charAt(0).toUpperCase() + part.slice(1).toLowerCase()
        ).join('-')
      }`;
      
      headers[headerName] = value;
      identifierCount++;
    });
    
    requestOptions.headers = headers;
  }
}

Protocol Schema Updates

Updated CallToolRequest:

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "arguments": { "type": "object" },
    "identifiers": {
      "type": "object",
      "additionalProperties": { "type": "string" },
      "description": "Optional identifiers to forward as HTTP headers"
    }
  },
  "required": ["name"]
}

Example Integration

Client usage:

// Configure client with default identifiers
const client = new Client({
  name: "my-app",
  version: "1.0.0",
  identifiers: {
    "trace-id": "abc-123",
    "tenant-id": "tenant-456"
  }
});

// Call tool with additional request-specific identifier
await client.callTool({
  name: "create_ticket",
  arguments: { title: "Bug report" },
  identifiers: { "request-id": "req-789" }
});

Resulting HTTP request to downstream API:

POST /api/tickets HTTP/1.1
X-MCP-Trace-Id: abc-123
X-MCP-Tenant-Id: tenant-456
X-MCP-Request-Id: req-789
Content-Type: application/json

{"title": "Bug report"}

This proposal would significantly improve MCP's observability and multi-tenancy capabilities while maintaining full backward compatibility. The automatic header forwarding in official SDKs ensures widespread adoption without requiring server developers to implement custom logic.