[v2] Decouple `server` from `express` and `hono` - http framework-agnostic MCP server #1326

KKonstantinov · 2025-12-20T11:52:41Z

v1 included express (and hono in recent version), forcing the dependency down to users. (express being >1MB along with middleware deps such as express-rate-limit etc.).

Achieving final & true implementation of #1299

This PR decouples @modelcontextprotocol/server from HTTP frameworks completely, and introduces three middleware packages: @modelcontextprotocol/node, @modelcontextprotocol/express, @modelcontextprotocol/hono.

The middleware packages are optional, and users could choose to use them or to map to the MCP SDK themselves and not using any of these plugins.

However, the @modelcontextprotocol/server is completely HTTP framework dependency-free.

Some additional changes:

Renamed StreamableHTTPServerTransport to NodeStreamableHTTPServerTransport
Added linting rule to avoid inline type imports (e.g. import { A, type B}). Prefer import type { B } and import { A } on separate lines.
Removed express dependency from @modelcontextprotocol/server completely
introduced @modelcontextprotocol/server-express and @modelcontextprotocol/server-hono - each having its own minimum dependencies
Removed sse transport for server (deprecated)
Removed server auth
Replaced examples for server auth with an OAuth library (e.g. better-auth)
Wrote up FAQ sections for removing SSE from server and removing auth from server
Tested better-auth server auth demo examples with @modelcontextprotocol/inspector
Updated express to 5.2.1 to get rid of CVE reported on 5.0.1 on the qs library (https://security.snyk.io/vuln/SNYK-JS-QS-14724253)
Updated existing docs, introduced new docs for middleware packages and general middleware doc

Motivation and Context

v2

How Has This Been Tested?

Unit tests

Breaking Changes

v2

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

…server-hono

…port, add server-express, server-hono to pkg.pr.new

changeset-bot · 2025-12-20T11:52:44Z

⚠️ No Changeset found

Latest commit: 7efc9ae

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

pkg-pr-new · 2025-12-20T11:54:37Z

Open in StackBlitz

@modelcontextprotocol/client

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/client@1326

@modelcontextprotocol/server

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/server@1326

@modelcontextprotocol/express

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/express@1326

@modelcontextprotocol/hono

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/hono@1326

@modelcontextprotocol/node

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/node@1326

commit: 7efc9ae

…b request

…examples, update faq

43081j · 2026-01-09T20:59:43Z

how are you calculating those sizes? they look too big to be the production install size, is it the size of your local server/node_modules including devDeps?

it might be worth including the production install size since that'll be what affects most people

a quick glance at it shows me the server is roughly ~9MB in main, and 6.5MB in your branch. huge saving!

… middleware folder, move express and hono to middleware folder

packages/core/src/shared/protocol.ts

43081j · 2026-01-13T09:36:15Z

I noticed the node middleware declares the server as a peer, but the other two declare it as a dependency.

should the three be consistent?

also - might it be a good idea to set hono and express as peers rather than dependencies? since these middlewares are meant to be used with them

pcarleton

Auth pieces LGTM!

KKonstantinov · 2026-01-13T11:11:06Z

I noticed the node middleware declares the server as a peer, but the other two declare it as a dependency.

should the three be consistent?

also - might it be a good idea to set hono and express as peers rather than dependencies? since these middlewares are meant to be used with them

Nice catch, yes, all middlewares should have these in peers, including @modelcontextprotocol/server (which should be a peer dep and not baked into middlewares).

.gitignore

pcarleton

Sorry missed this earlier, but the PRM path needs to have the pathname after .well-known rather than before

examples/shared/src/authMiddleware.ts

…com:KKonstantinov/typescript-sdk into feature/v2-decouple-web-servers-from-server

felixweinberger

Nice refactor! Looked through and this LGTM except for @pcarleton's point above which would be great to address.

packages/server/src/server/helper/body.ts

KKonstantinov · 2026-01-15T14:19:30Z

Done!

Nice refactor! Looked through and this LGTM except for @pcarleton's point above which would be great to address.

@pcarleton

Dismissing @pcarleton's review as I believe his change request has been addressed

KKonstantinov added 3 commits December 20, 2025 08:56

PoC: split away server express and hono deps into server-express and …

5958449

…server-hono

remove rate limiting from core server, move to express only

354fb43

rename StreamableHttpServerTransport to NodeStreamableHttpServerTrans…

564aed2

…port, add server-express, server-hono to pkg.pr.new

merge commit

5b79322

KKonstantinov added 9 commits December 20, 2025 15:19

move back to hono/node-server for mapping incoming node request to we…

223fcb0

…b request

hono-server updates

aaeff28

PoC: remove sse, remove server auth, use better-auth for server auth …

4b7fcb0

…examples, update faq

lint fix

d52565e

oAuth metadata: switch to better-auth/plugins -> mcp plugin

62656b4

working better-auth example

7dc044b

lint fix

8dba772

clean up

45f0ef1

package clean up

f5ab824

KKonstantinov marked this pull request as ready for review December 22, 2025 11:36

KKonstantinov requested a review from a team as a code owner December 22, 2025 11:36

KKonstantinov added breaking change Will break existing deployments when updated without changes auth Issues and PRs related to Authentication / OAuth v2 Ideas, requests and plans for v2 of the SDK which will incorporate major changes and fixes labels Dec 22, 2025

This was linked to issues Dec 22, 2025

SDK V2 #809

Closed

Decouple from Express: support other HTTP frameworks #1299

Closed

KKonstantinov self-assigned this Dec 22, 2025

KKonstantinov added this to the v2 milestone Dec 22, 2025

KKonstantinov and others added 3 commits January 1, 2026 22:45

update express to 5.2.1

71297bc

Merge branch 'main' into feature/v2-decouple-web-servers-from-server

443abca

Merge branch 'main' into feature/v2-decouple-web-servers-from-server

0e14e49

KKonstantinov and others added 2 commits January 12, 2026 17:12

Merge branch 'main' into feature/v2-decouple-web-servers-from-server

fef0b46

merge commit

6c21c50

KKonstantinov added 2 commits January 12, 2026 17:56

split @modelcontextprotocol/node from @modelcontextprotocol/server to…

304d111

… middleware folder, move express and hono to middleware folder

lint, test fix

4c29404

KKonstantinov requested a review from mattzcarey January 12, 2026 16:57

auth examples - demo flag, configs

ce58234

43081j reviewed Jan 13, 2026

View reviewed changes

packages/core/src/shared/protocol.ts Outdated Show resolved Hide resolved

pcarleton reviewed Jan 13, 2026

View reviewed changes

package clean up, peer deps on middleware, comment fix

635c37b

KKonstantinov added 5 commits January 13, 2026 13:11

peer deps update

c154cbb

update READMEs

96fd273

lint fix

c174fe4

merge commit

e5a8edc

merge commit

70c348d

43081j reviewed Jan 13, 2026

View reviewed changes

.gitignore Outdated Show resolved Hide resolved

KKonstantinov and others added 2 commits January 13, 2026 23:15

fix merge

ed9c27b

Merge branch 'main' into feature/v2-decouple-web-servers-from-server

bcb4cdb

pcarleton previously requested changes Jan 14, 2026

View reviewed changes

examples/shared/src/authMiddleware.ts Show resolved Hide resolved

KKonstantinov and others added 3 commits January 15, 2026 09:59

Merge branch 'main' into feature/v2-decouple-web-servers-from-server

7b85e73

PRM path fix

e77f19c

Merge branch 'feature/v2-decouple-web-servers-from-server' of github.…

355a9f4

…com:KKonstantinov/typescript-sdk into feature/v2-decouple-web-servers-from-server

felixweinberger previously approved these changes Jan 15, 2026

View reviewed changes

packages/server/src/server/helper/body.ts Outdated Show resolved Hide resolved

getParsedBody clean up

1223ddc

KKonstantinov dismissed felixweinberger’s stale review via 1223ddc January 15, 2026 14:21

body helper export remove

7efc9ae

felixweinberger approved these changes Jan 16, 2026

View reviewed changes

KKonstantinov merged commit f495077 into modelcontextprotocol:main Jan 16, 2026
9 checks passed

domdomegg mentioned this pull request Jan 16, 2026

bug: invalid types for sessionIdGenerator in 1.25.2 #1397

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[v2] Decouple `server` from `express` and `hono` - http framework-agnostic MCP server #1326

[v2] Decouple `server` from `express` and `hono` - http framework-agnostic MCP server #1326

KKonstantinov commented Dec 20, 2025 •

edited

Loading

Uh oh!

changeset-bot bot commented Dec 20, 2025 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Dec 20, 2025 •

edited

Loading

Uh oh!

43081j commented Jan 9, 2026 •

edited

Loading

Uh oh!

Uh oh!

43081j commented Jan 13, 2026

Uh oh!

pcarleton left a comment

Uh oh!

KKonstantinov commented Jan 13, 2026 •

edited

Loading

Uh oh!

Uh oh!

pcarleton left a comment

Uh oh!

Uh oh!

felixweinberger left a comment

Uh oh!

Uh oh!

KKonstantinov commented Jan 15, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

[v2] Decouple server from express and hono - http framework-agnostic MCP server #1326

[v2] Decouple server from express and hono - http framework-agnostic MCP server #1326

Conversation

KKonstantinov commented Dec 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Uh oh!

changeset-bot bot commented Dec 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

pkg-pr-new bot commented Dec 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

43081j commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

43081j commented Jan 13, 2026

Uh oh!

pcarleton left a comment

Choose a reason for hiding this comment

Uh oh!

KKonstantinov commented Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

pcarleton left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

felixweinberger left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

KKonstantinov commented Jan 15, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

[v2] Decouple `server` from `express` and `hono` - http framework-agnostic MCP server #1326

[v2] Decouple `server` from `express` and `hono` - http framework-agnostic MCP server #1326

KKonstantinov commented Dec 20, 2025 •

edited

Loading

changeset-bot bot commented Dec 20, 2025 •

edited

Loading

pkg-pr-new bot commented Dec 20, 2025 •

edited

Loading

43081j commented Jan 9, 2026 •

edited

Loading

KKonstantinov commented Jan 13, 2026 •

edited

Loading