enable http headers in sse in the context

[abdullahkady]

Motivation and Context

In the server, it seems like a common case to need to access the raw HTTP headers (think a reverse proxy header, or some custom analytics headers).

Example use case, where we have two services that can possibly talk to the MCP server. The servers identify themselves through the X-Client HTTP header.

from mcp.server.fastmcp import Context, FastMCP

mcp = FastMCP("test_w_headers", port=3001, debug=True)


@mcp.tool()
def add_sales_lead(lead: str, ctx: Context) -> str:
    """
	Adds a new sales lead. Tracks which app was the originator of 
	this request based on the X-Client custom header
	"""
	sales.add_lead(lead, tracking_attrs={"src": ctx.headers.get("X-Client")}
    return "Lead added successfully"

How Has This Been Tested?

They were just tested manually locally

Breaking Changes

No

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

[dsp-ant]

I think the general idea to give access to headers in the context is great. I think we should focus on exposing the headers from the transport protocol (HTTP Headers in HTTP+SSE transport and no headers in STDIO) inside the context.

[dsp-ant]

I don't think we would want to add headers to the types. The types are a direct translation of the schema.ts in the specification. Adding headers here would not be compatible with JSON-RPC in it's most used form.

[abdullahkady]

@dsp-ant Thank you! That's fair. I was trying to initially do the change such that only the sse file is the one with changes, but here's my problem, and a suggestion for an approach to fix it. Please correct me if my understanding of the code is not complete.

• The HTTP request is only available in transport layer (sse.py)
• The only way to pass stuff down from the transport layer to the server implementation is going to be through the streams, which have JSONRPCMessage type
• We don't want to extend/change the JSONRPCMessage type because it is part of the schema (and honestly it makes sense, since it only applies to certain transports)

To solve this, here are my other 2 suggestions:

• Inject the metadata (one of which is optional headers) in the params of the JSONRPCMessage
• Change the streams so that they now hold a new type (a container type with the JSONRPCMessage + meta), where the meta can be anything that is transport-specific?

Let me know what you think.

[dsp-ant]

I assume we most likely want headers to be extracted from the transport protocol itself. This means providing ways within a session context to access to original request headers for the HTTP Post in the case of SSE. For STDIO this would be empty. If we ever come to the conclusion that headers are absolutely necessary, I think we likely would move to a STDIO transport description that is akin to the header-based JSON-RPC that LSP is doing, which is of the form:

Some-Header: Some-Value
Some-Header: Some-Value
{"jsonrpc": "2.0", ...}

Re-Review

[dsp-ant]

Thanks for doing that. I really like the idea and just working through an alternative option. Will have something soon.