enable http headers in sse in the context #216

abdullahkady · 2025-02-19T01:04:42Z

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 · 2025-02-19T14:45:48Z

src/mcp/types.py

@@ -118,6 +118,7 @@ class JSONRPCRequest(Request):
    jsonrpc: Literal["2.0"]
    id: RequestId
    params: dict[str, Any] | None = None
+    headers: dict[str, str] | None = None


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.

@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 hey, any chance you have given this some thought and have any guidance for the approach? I would love to update the PR

dsp-ant · 2025-02-19T14:47:59Z

src/mcp/server/lowlevel/server.py

+            headers = {}
+            try:
+                # TODO: This try/catch and ignoring the type is wrong.
+                headers = message.request.root.headers  # type: ignore
+            except Exception:
+                pass


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 · 2025-02-26T11:52:12Z

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

gdoctor · 2025-03-21T17:42:32Z

Adding my input here in case anyone has the same use case as me.

I am building an MCP Client. I need to be able to set different headers on a per-request basis. In my use-case, it's to differentiate users interacting with my client, among other things. Right now, you can only set headers when creating a new ClientSession, but I want to maintain semi-persistent ClientSession(s). This PR seems to address this in it's current state, while also making it easier to consume headers on the Server side. I understand there is some discussion on the best way to do this still, but the need is there for all us MCP Client creators.

vivek-athina · 2025-03-25T07:24:08Z

@dsp-ant Any update on this ? It will be really useful if this can be achieved out of the box.

ZAKLLL · 2025-04-24T03:44:49Z

support this pr ,and it will be useful in sse/streamhttp server,like env config in stdio ,i think http metadata is also necessary in sse mcp ，otherwise , the client cannot determine custom config expect request param ,it not suitable , of course ,it should be declared clearly in docs that header metadata just available in sse/streamhttp mcp server!

sidey · 2025-05-10T18:45:46Z

I don't think this PR is a good solution.since context was implemented by contextvar,if some one wants to fetch the header of a http request.he can do it in a similar way.
eg. set a contextvar in a starlette middleware and then retrieve it anywhere.
I wonder what's your solution about this feature request.@dsp-ant

abdullahkady added 2 commits February 18, 2025 19:45

enable http headers in sse in the context

144db31

add todo comment

e402103

dsp-ant requested review from dsp-ant, jerome3o-anthropic and jspahrsummers February 19, 2025 14:38

dsp-ant previously requested changes Feb 19, 2025

View reviewed changes

type instead of try/except

b6e4576

abdullahkady marked this pull request as draft February 19, 2025 15:50

abdullahkady requested a review from dsp-ant February 20, 2025 16:11

abdullahkady marked this pull request as ready for review February 21, 2025 16:53

Merge branch 'main' into main

1f146f6

lochiiconnectivity mentioned this pull request Apr 14, 2025

Support HTTP Headers in SSE Context jlowin/fastmcp#157

Closed

ihrpr mentioned this pull request May 13, 2025

Added support for raw request injection in RequestContext. #380

Open

7 tasks

ihrpr added this to the r-05-25 milestone May 13, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

enable http headers in sse in the context #216

enable http headers in sse in the context #216

abdullahkady commented Feb 19, 2025 •

edited

Loading

dsp-ant left a comment

dsp-ant Feb 19, 2025

abdullahkady Feb 20, 2025

abdullahkady Mar 17, 2025

dsp-ant Feb 19, 2025

dsp-ant commented Feb 26, 2025

gdoctor commented Mar 21, 2025

vivek-athina commented Mar 25, 2025

ZAKLLL commented Apr 24, 2025

sidey commented May 10, 2025 •

edited

Loading

enable http headers in sse in the context #216

Are you sure you want to change the base?

enable http headers in sse in the context #216

Conversation

abdullahkady commented Feb 19, 2025 • edited Loading

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Additional context

dsp-ant left a comment

Choose a reason for hiding this comment

dsp-ant Feb 19, 2025

Choose a reason for hiding this comment

abdullahkady Feb 20, 2025

Choose a reason for hiding this comment

abdullahkady Mar 17, 2025

Choose a reason for hiding this comment

dsp-ant Feb 19, 2025

Choose a reason for hiding this comment

dsp-ant commented Feb 26, 2025

gdoctor commented Mar 21, 2025

vivek-athina commented Mar 25, 2025

ZAKLLL commented Apr 24, 2025

sidey commented May 10, 2025 • edited Loading

abdullahkady commented Feb 19, 2025 •

edited

Loading

sidey commented May 10, 2025 •

edited

Loading