add support for Streamable HTTP server #294

shivdeepak · 2025-04-10T03:59:55Z

Motivation and Context

typescript-sdk recently added support for Streamable HTTP client, and server. This PR leverages that change, and adds support for Streamable HTTP MCP Servers to inspector.

Other language bindings are also adding support for streamable HTTP. Integrating this change to the inspector will help towards those efforts by making testing and debugging easy.

Note that I am marking this PR as work in progress (WIP) because this PR cannot use the Streamable HTTP Client and Sever from typescript-sdk until a version bump.

How Has This Been Tested?

Clone this branch, and start the inspector locally

npm run dev

Caveat: You will have to manually build the latest typescript-sdk so that Streamable HTTP Client is available.

Once you have everything up and running. You should be able to see the new Streamable HTTP transport type.

Now, on a different terminal session, clone typescript-sdk and run.

npx tsx src/examples/server/simpleStreamableHttp.ts

This will start a Streamable HTTP MCP Server at http://localhost:3000/mcp

Connect to it, and you should be able to issue commands.

Here is an example tools/list command:

Here is an example ping command:

Breaking Changes

Currently this branch only works when typescript-sdk is built from the latest main. Therefore marking this PR as WIP.

There shouldn't be any breaking changes once there is a version bump in typescript-sdk and we update package.json here.

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

shivdeepak · 2025-04-10T04:01:51Z

@cliffhall @jspahrsummers @pulkitsharma07 would appreciate some early feedback on this. 🙂

cliffhall · 2025-04-10T15:27:12Z

@cliffhall @jspahrsummers @pulkitsharma07 would appreciate some early feedback on this. 🙂

Hi @shivdeepak!

Looks ok, but once the SDK version is bumped, we'll be able to test this more thoroughly. Hopefully that'll take place today. I have a PR queued up for it.

ChrisLally · 2025-04-10T17:12:31Z

we've got streamable http support live in https://inspect.mcp.garden for anyone that wants to try in the meantime!

cliffhall · 2025-04-11T21:43:56Z

BTW, while modelcontextprotocol/typescript-sdk#305 has been merged, there are a few remaining bits such as resumability to be added to the SDK before we actually tag and publish its next release. As soon as it's good, we'll be doing a new inspector release.

ihrpr · 2025-04-17T19:07:01Z

@cliffhall, @shivdeepak TypeScript SDK new version is out now

cliffhall · 2025-04-17T20:40:35Z

@cliffhall, @shivdeepak TypeScript SDK new version is out now

In order to test this, I will add streamable support to the everything server.

shivdeepak · 2025-04-17T23:15:18Z

@cliffhall what is the everything server. do you need any support from my end?

dukex · 2025-04-18T02:49:39Z

server/src/index.ts

@@ -94,6 +95,13 @@ const createTransport = async (req: express.Request): Promise<Transport> => {

    console.log("Connected to SSE transport");
    return transport;
+  } else if (transportType === "streamable-http") {
+    const transport = new StreamableHTTPClientTransport(


To Auth feature works you should send headers to the server

Suggested change

const transport = new StreamableHTTPClientTransport(

const STREAMABLE_HTTP_HEADERS_PASSTHROUGH = ["authorization"];

const headers: HeadersInit = {};

for (const key of STREAMABLE_HTTP_HEADERS_PASSTHROUGH) {

if (req.headers[key] === undefined) {

continue;

}

const value = req.headers[key];

headers[key] = Array.isArray(value) ? value[value.length - 1] : value;

}

const transport = new StreamableHTTPClientTransport(

Thanks. I have added the recommended changes and tested them. They work well.

MCP Inspector

Req/Resp Headers

cliffhall · 2025-04-18T19:06:06Z

@cliffhall what is the everything server. do you need any support from my end?

@shivdeepak, if you wanted to make a PR for this, it shouldn't be hard and it would help test this PR.

The everything server in the servers repo is a handy one to pair with Inspector work. It attempts to exercise most of the protocol features on the server side.
There is already an issue for adding the streaming http functionality to it: Update Everything server to use version 2025-03-26 support for HTTP transport servers#1247
Basically we need a streamingHttp version of its sse.ts server wrapper.
We can then launch the inspector with your changes, connect to that server and make sure it works as expected.

shivdeepak · 2025-04-19T00:46:13Z

@cliffhall, thanks for the additional info. I don't mind picking this up -- I will create a PR for it soon.

cliffhall

Excellent work @shivdeepak.

I tested with

streamableHttp using your additions to the everything server.
stdio using local path to GooseTeam stdio server.
sse using the everything server's sse.ts
sse with oauth using this handy demo by @max-stytch (using /sse endpoint instead of the /login in the link)

ferrants · 2025-04-21T08:09:28Z

Thanks for this! I am using it and it's working pretty well for a session-less MCP Streamable HTTP Server.

I ran into two potential issues, though probably just missing functionality with the new Streamable HTTP type, not any regressions.

For using a session, the inspector doesn't appear to be retaining the session id header: mcp-session-id and sending it with subsequent requests reliably.
I get intermittent Error POSTing to endpoint (HTTP 500): SSE connection not established errors for both the sessioned mcp server and no-session mcp server. It's not clear to me why it's intermittent. The request doesn't appear to be making it out of the inspector (no logging in the MCP server from the request). And when it fails, I see an error about the inspector request and setting of headers:

Received message for sessionId b12b7c97-65e4-4a61-9a71-d58cfaaa75a7
Error in /message route: Error: SSE connection not established
    at SSEServerTransport.handlePostMessage (file:///home/matt/code/inspector/node_modules/@modelcontextprotocol/sdk/dist/esm/server/sse.js:61:19)
    at file:///home/matt/code/inspector/server/build/index.js:150:25
    at Layer.handleRequest (/home/matt/code/inspector/node_modules/router/lib/layer.js:152:17)
    at next (/home/matt/code/inspector/node_modules/router/lib/route.js:157:13)
    at Route.dispatch (/home/matt/code/inspector/node_modules/router/lib/route.js:117:3)
    at handle (/home/matt/code/inspector/node_modules/router/index.js:435:11)
    at Layer.handleRequest (/home/matt/code/inspector/node_modules/router/lib/layer.js:152:17)
    at /home/matt/code/inspector/node_modules/router/index.js:295:15
    at processParams (/home/matt/code/inspector/node_modules/router/index.js:582:12)
    at next (/home/matt/code/inspector/node_modules/router/index.js:291:5)
Error [ERR_HTTP_HEADERS_SENT]: Cannot set headers after they are sent to the client
    at new NodeError (node:internal/errors:406:5)
    at ServerResponse.setHeader (node:_http_outgoing:652:11)
    at ServerResponse.header (/home/matt/code/inspector/node_modules/express/lib/response.js:684:10)
    at ServerResponse.json (/home/matt/code/inspector/node_modules/express/lib/response.js:247:10)
    at file:///home/matt/code/inspector/server/build/index.js:154:25
    at process.processTicksAndRejections (node:internal/process/task_queues:95:5)
New SSE connection
Query parameters: [Object: null prototype] {
  transportType: 'streamable-http',
  url: 'http://localhost:3002/mcp'
}

cliffhall · 2025-04-21T14:30:47Z

Hi @ferrants

Thanks for the report. In order to put this one through its paces, we've needed a server for testing, and that was the everything server in the example servers repo. Testing of these changes against it worked fine, but it has subsequently cast light on a bug in this implementation. We're working on that.

add support for streamable http server

638603c

run prettier-fix

f43a914

shivdeepak changed the title ~~add support for Streamable HTTP server [WIP]~~ add support for Streamable HTTP server Apr 10, 2025

cliffhall mentioned this pull request Apr 10, 2025

Bump to version 1.10.0 modelcontextprotocol/typescript-sdk#305

Merged

10 tasks

cliffhall requested a review from tadasant April 10, 2025 16:33

cliffhall added enhancement New feature or request waiting on sdk Waiting for an SDK feature labels Apr 11, 2025

Merge branch 'main' into main

b397125

shivdeepak marked this pull request as ready for review April 17, 2025 23:18

jmorrell-cloudflare mentioned this pull request Apr 17, 2025

3/ Add support for HTTP Streamable MCP Transport cloudflare/agents#186

Merged

dukex reviewed Apr 18, 2025

View reviewed changes

shivdeepak force-pushed the main branch from 89edbf5 to b397125 Compare April 18, 2025 04:33

shivdeepak added 2 commits April 17, 2025 21:33

Merge branch 'main' into main

3617863

attach auth headers to the streamable http request

8213402

cliffhall removed the waiting on sdk Waiting for an SDK feature label Apr 18, 2025

shivdeepak mentioned this pull request Apr 19, 2025

add streamableHttp server support for everything server modelcontextprotocol/servers#1496

Merged

12 tasks

cliffhall approved these changes Apr 19, 2025

View reviewed changes

cliffhall merged commit 6ab7ac3 into modelcontextprotocol:main Apr 19, 2025
2 checks passed

cliffhall mentioned this pull request Apr 21, 2025

Fix support for streamable-http connections #339

Merged

9 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

add support for Streamable HTTP server #294

add support for Streamable HTTP server #294

shivdeepak commented Apr 10, 2025 •

edited

Loading

shivdeepak commented Apr 10, 2025

cliffhall commented Apr 10, 2025

ChrisLally commented Apr 10, 2025

cliffhall commented Apr 11, 2025

ihrpr commented Apr 17, 2025

cliffhall commented Apr 17, 2025

shivdeepak commented Apr 17, 2025

dukex Apr 18, 2025

shivdeepak Apr 18, 2025 •

edited

Loading

cliffhall commented Apr 18, 2025

shivdeepak commented Apr 19, 2025

cliffhall left a comment

ferrants commented Apr 21, 2025

cliffhall commented Apr 21, 2025

-    const transport = new StreamableHTTPClientTransport(
+    const STREAMABLE_HTTP_HEADERS_PASSTHROUGH = ["authorization"];
+    const headers: HeadersInit = {};
+    for (const key of STREAMABLE_HTTP_HEADERS_PASSTHROUGH) {
+      if (req.headers[key] === undefined) {
+        continue;
+      }
+      const value = req.headers[key];
+      headers[key] = Array.isArray(value) ? value[value.length - 1] : value;
+    }
+    const transport = new StreamableHTTPClientTransport(

add support for Streamable HTTP server #294

add support for Streamable HTTP server #294

Conversation

shivdeepak commented Apr 10, 2025 • edited Loading

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Additional context

shivdeepak commented Apr 10, 2025

cliffhall commented Apr 10, 2025

ChrisLally commented Apr 10, 2025

cliffhall commented Apr 11, 2025

ihrpr commented Apr 17, 2025

cliffhall commented Apr 17, 2025

shivdeepak commented Apr 17, 2025

dukex Apr 18, 2025

Choose a reason for hiding this comment

shivdeepak Apr 18, 2025 • edited Loading

Choose a reason for hiding this comment

cliffhall commented Apr 18, 2025

shivdeepak commented Apr 19, 2025

cliffhall left a comment

Choose a reason for hiding this comment

ferrants commented Apr 21, 2025

cliffhall commented Apr 21, 2025

shivdeepak commented Apr 10, 2025 •

edited

Loading

shivdeepak Apr 18, 2025 •

edited

Loading