GitHub - MohibShaikh/mcp-uplift: Run legacy MCP stdio servers behind the 2026-07-28 protocol. Translates the removed initialize handshake, sessions, and server-initiated requests. · GitHub

/" data-turbo-transient="true" />

Skip to content

Type / to search

Sign in<br>Sign upAppearance settings

You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.

Dismiss alert

{{ message }}

MohibShaikh

mcp-uplift

Public

Notifications<br>You must be signed in to change notification settings

Fork

Star

main

BranchesTags

Go to file

CodeOpen more actions menu

Folders and files<br>NameNameLast commit message<br>Last commit date<br>Latest commit

History<br>10 Commits<br>10 Commits

docs

docs

src

src

test

test

.gitignore

.gitignore

LICENSE

LICENSE

README.md

README.md

package.json

package.json

View all files

Repository files navigation

mcp-uplift

MCP 2026-07-28 removed the initialization handshake, sessions, ping,<br>logging configuration, resource subscriptions, and server-initiated requests.<br>Older MCP servers still use those protocol features. mcp-uplift wraps one<br>legacy stdio server and presents it as a modern stateless server.

Security: wrapping a server executes that server with your operating-system<br>permissions. This bridge is not a sandbox. Only run packages and commands you<br>trust.

Demo

The unmodified official @modelcontextprotocol/server-filesystem running behind<br>the 2026-07-28 protocol: server/discover is synthesized from the legacy<br>handshake, the server's own roots/list request becomes a keyed input_required<br>result, and answering it resumes the call and returns all 14 tools.

Usage

Run without installing:

[args...]">npx mcp-uplift legacy-command> [args...]

For example:

npx mcp-uplift npx -y @modelcontextprotocol/server-filesystem /tmp

The wrapped command receives a minimal environment by default. Forward a needed<br>credential explicitly, before --:

npx mcp-uplift --env BRAVE_API_KEY -- npx -y @modelcontextprotocol/server-brave-search

--inherit-env is available for compatibility but exposes every environment<br>variable to the wrapped process. Run npx mcp-uplift --help for resource and<br>timeout controls.

Client configuration

Before, a client launches the legacy server directly:

"mcpServers": {<br>"files": {<br>"command": "npx",<br>"args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]

After, launch the same command through mcp-uplift:

"mcpServers": {<br>"files": {<br>"command": "npx",<br>"args": ["mcp-uplift", "npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp"]

Compatibility

Because 2026-07-28 is stateless, every request must carry its own envelope in<br>params._meta: the protocol version and the client's capabilities, plus<br>optional client identity. A request missing them is rejected rather than<br>guessed at.

"jsonrpc": "2.0",<br>"id": 1,<br>"method": "tools/list",<br>"params": {<br>"_meta": {<br>"io.modelcontextprotocol/protocolVersion": "2026-07-28",<br>"io.modelcontextprotocol/clientCapabilities": { "roots": {} },<br>"io.modelcontextprotocol/clientInfo": { "name": "my-client", "version": "1.0.0" }

If a wrapped server needs a capability the client did not declare, the bridge<br>returns -32021 naming what was required, rather than failing deep inside the<br>call.

Feature<br>Behavior

Legacy initialize<br>Performed once and exposed as server/discover

Per-request version metadata<br>Validated as 2026-07-28, else -32022

Tools, prompts, and resources<br>Forwarded with modern result and cache metadata

Legacy resource-not-found errors<br>Mapped from -32002 to -32602

Sampling, elicitation, and roots requests<br>Translated into multi-round-trip input_required results

Removed methods<br>Rejected with -32601 method-not-found

Upstream failures<br>Returned as -32603 internal errors

Known limitations

Real-world validation confirmed discovery and tool listing against 39 distinct<br>legacy MCP packages. The official filesystem server also completed a real<br>roots/list MRTR round trip and returned all 14 tools. These are tested<br>examples, not a guarantee that every server or session-dependent behavior can<br>be translated.

All legacy calls are serialized. The<br>legacy protocol never links a sampling/createMessage, elicitation/create,<br>or roots/list request back to the call that caused it, so the bridge<br>keeps one call in flight through all of its MRTR rounds. This favors correct<br>attribution over throughput.

Legacy notifications have no home and are dropped. 2026-07-28 moved<br>streamed notifications onto a dedicated subscriptions/listen stream; this<br>bridge is a plain one-request-one-response stdio proxy and does not<br>implement that stream, so notifications/progress and<br>notifications/message from the wrapped server are discarded rather than<br>delivered.

Real-server checks require downloads and remain outside the offline suite.

The kill switch terminates the launched process tree on POSIX and...