René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Support Per-Request HTTP Headers in call_tool()","articleBody":"### Description\n\n\n**Related Issues**: #638, #600, #1305\n\n\nSummary\n\nAdd support for passing custom HTTP headers on a per-request basis when calling MCP tools via `ClientSession.call_tool()`. This is needed for multi-tenant applications where different requests require different authentication tokens or request-specific metadata headers while maintaining a single persistent MCP connection.\n\nUse Case: Multi-Tenant SaaS Applications\n\nIn multi-tenant deployments, a single application instance serves multiple users/tenants concurrently. Each user request needs to include tenant-specific authentication headers when calling MCP tools, but creating a new MCP connection per request introduces unacceptable latency:\n\n- Connection establishment: ~500ms overhead per request\n- At 1000 concurrent users: 8.3 minutes of cumulative overhead per minute\n- Connection pooling doesn't help because each user needs different headers\n\nCurrent State: Headers can only be set at connection initialization in `streamablehttp_client()`, making them static for the connection lifetime.\n\nDesired State: Ability to pass custom headers per `call_tool()` invocation while maintaining a single persistent connection.\n\nRelated Use Cases\n\nThis pattern appears in several scenarios:\n\n1. Per-request authentication - Different auth tokens per user (Issue #638)\n2. Request tracing - Correlation IDs, trace IDs for distributed systems\n3. Rate limiting - User-specific rate limit tokens\n4. A/B testing - Feature flags or experiment IDs\n5. Tenant isolation - Tenant identifiers for data partitioning\n\nCurrent Behavior\n\n```python\nfrom mcp.client.streamable_http import streamablehttp_client\n\n# Headers set at connection time - static for connection lifetime\nasync with streamablehttp_client(\n    url=\"https://mcp.example.com\",\n    headers={\"Authorization\": \"Bearer static-token\"},  # Cannot change per-request\n) as (read_stream, write_stream, get_session_id):\n    async with ClientSession(read_stream, write_stream) as session:\n        # User A's request\n        result = await session.call_tool(\"list_sites\", {})  # Uses static token\n        \n        # User B's request (needs different token)\n        result = await session.call_tool(\"list_sites\", {})  # Still uses static token\n```\n\nProposed Solution\n\nOption 1: Add `extra_headers` Parameter to `call_tool()`\n\nSimilar to how `read_timeout_seconds` was added for per-request timeout configuration (Issue #600), add an optional parameter for per-request headers:\n\n```python\nasync def call_tool(\n    self,\n    name: str,\n    arguments: dict[str, Any] | None = None,\n    read_timeout_seconds: timedelta | None = None,\n    progress_callback: ProgressFnT | None = None,\n    *,\n    meta: dict[str, Any] | None = None,\n    extra_headers: dict[str, str] | None = None,  # NEW\n) -\u003e types.CallToolResult:\n    \"\"\"\n    Send a tools/call request.\n    \n    Args:\n        extra_headers: Additional HTTP headers to include in this specific request.\n                      These are merged with connection-level headers, with extra_headers\n                      taking precedence for duplicate keys.\n    \"\"\"\n```\n\n**Usage Example**:\n\n```python\nasync with streamablehttp_client(\n    url=\"https://mcp.example.com\",\n    headers={\"Authorization\": \"Bearer org-token\"},  # Organization-level auth\n) as (read_stream, write_stream, get_session_id):\n    async with ClientSession(read_stream, write_stream) as session:\n        # User A's request\n        result = await session.call_tool(\n            \"list_sites\",\n            {},\n            extra_headers={\"X-Auth-Token\": \"user-a-token\", \"X-Trace-Id\": \"trace-123\"}\n        )\n        \n        # User B's request\n        result = await session.call_tool(\n            \"list_sites\",\n            {},\n            extra_headers={\"X-Auth-Token\": \"user-b-token\", \"X-Trace-Id\": \"trace-456\"}\n        )\n```\n\nImplementation Notes:\n\n1. Modify `ClientSession.call_tool()` signature to accept `extra_headers`\n2. Pass headers to transport layer via request context\n3. In `StreamableHTTPTransport._handle_post_request()`, merge extra_headers with base headers\n4. Extra headers take precedence over connection-level headers for duplicate keys\n\n\nOption 2: Extend Transport Context\n\nAdd headers to the existing `RequestContext` mechanism:\n\n```python\n# In StreamableHTTPTransport\nasync def _handle_post_request(\n    self, \n    ctx: RequestContext,\n    extra_headers: dict[str, str] | None = None  # NEW\n) -\u003e None:\n    headers = self._prepare_request_headers(ctx.headers)\n    if extra_headers:\n        headers.update(extra_headers)  # Merge per-request headers\n    \n    async with ctx.client.stream(\"POST\", self.url, json=message, headers=headers):\n        ...\n```\n\nBackward Compatibility\n\nAll proposed solutions are backward compatible:\n\n- `extra_headers` parameter is optional (defaults to `None`)\n- Existing code continues to work unchanged\n- No breaking changes to MCP protocol or message format\n- Headers are HTTP transport-specific, not part of JSON-RPC messages\n\nPrecedent\n\nThe SDK already supports per-request configuration for timeouts:\n\n```python\nresult = await session.call_tool(\n    \"slow_operation\",\n    {},\n    read_timeout_seconds=timedelta(seconds=120)  # Per-request timeout\n)\n```\n\nThis establishes a pattern that certain aspects of tool invocation may need per-request customization beyond the JSON-RPC protocol itself.\n\n\nNon-Solution: Per-Request Connections\n\nCreating a new connection per request defeats the purpose of persistent connections and introduces significant latency overhead.\n\n\nImplementation Considerations\n\nHeader Merging Strategy\n\nConnection-level headers should be merged with per-request headers:\n\n```python\ndef _merge_headers(\n    base_headers: dict[str, str],\n    extra_headers: dict[str, str] | None\n) -\u003e dict[str, str]:\n    \"\"\"Merge headers with extra_headers taking precedence.\"\"\"\n    merged = base_headers.copy()\n    if extra_headers:\n        merged.update(extra_headers)\n    return merged\n```\n\nTransport-Specific\n\nThis feature should only affect HTTP-based transports (Streamable HTTP, SSE). Stdio transport would ignore `extra_headers` as it has no HTTP layer.\n\nSecurity Considerations\n\nPer-request headers enable proper security patterns:\n\n- Least-privilege: Each request carries only the permissions it needs\n- Token rotation: Different tokens can be used without reconnecting\n- Audit trails: Request-specific correlation IDs for logging\n\n\nRelated Issues\n\n- #638 - FastMCP Auth Context in tools (same root problem)\n- #600 - Per-request timeout configuration (precedent for per-request parameters)\n- #1305 - Secure Tool/Resource/Prompt Decorators with Auth (related auth concern)\n\n\nI'm willing to contribute a pull request implementing this feature if the approach is acceptable to maintainers. Our production use case requires this functionality, and we believe it would benefit the broader MCP community.\n\nThanks,\nDamian.\n\n### References\n\n_No response_","author":{"url":"https://github.com/damianoneill","@type":"Person","name":"damianoneill"},"datePublished":"2025-10-23T13:07:34.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":8},"url":"https://github.com/1509/python-sdk/issues/1509"}