feat: Add custom context support for MCP transports

[grimmerk]

This PR adds support for passing custom context data from transport implementations to MCP handlers (tools, resources, prompts). This enables server implementations to inject application-specific context like tenant ID, user info, feature flags, etc. without relying on closures or global state.

Motivation and Context

Currently, MCP server implementations have no standard way to pass request-specific context (e.g., authentication/tenant data from MCP access tokens or API keys, service objects) from the transport layer to tool/resource/prompt handlers.. This limitation forces developers to use workarounds like closures or session-based context maps.

This PR solves this problem by:

• Adding a customContext field to MessageExtraInfo
• Passing it through RequestHandlerExtra to all handlers
• Providing a setCustomContext() method on all transport implementations

Implementation Details

Core Changes:

• types.ts: Added optional customContext?: Record<string, unknown> to MessageExtraInfo
• shared/protocol.ts: Added customContext to RequestHandlerExtra, passed through in _onrequest
• shared/transport.ts: Added optional setCustomContext() method to Transport interface

Transport Implementations:

• InMemoryTransport: Stores and merges custom context with message extra info
• SSEServerTransport: Injects custom context in handleMessage()
• StreamableHTTPServerTransport: Includes custom context in all onmessage() calls
• StdioServerTransport: Passes custom context with processed messages

Usage Example:

// Set custom context on transport
const transport =new StreamableHTTPServerTransport({
  sessionIdGenerator: undefined,
  enableJsonResponse: true, 
});

transport.setCustomContext({
  tenantId: authContext.user?.tenantId,
  userId: authContext.user?.id,
  featureFlags: { betaMode: true }
});

// Connect transport to server
await server.connect(transport);

// Access in tool handler
server.tool('search', async ({ query }, extra) => {
  const tenantId = extra.customContext?.tenantId;
  const userId = extra.customContext?.userId;
  // Use context for tenant-specific operations
});

How Has This Been Tested?

• ✅ Unit test added for InMemoryTransport custom context propagation
• ✅ Manually tested with SSE and Streamable HTTP transports in a real application
• ✅ All existing tests continue to pass
• ✅ Verified the same implementation pattern is applied consistently across all transports

Breaking Changes

None. All changes are backwards compatible:

• customContext is an optional field
• setCustomContext() is an optional method
• Existing code will continue to work without modifications

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

This feature was developed to address the need for multi-tenant MCP server implementations where request-specific context needs to be available throughout the handler chain. The implementation follows existing patterns in the codebase (similar to how authInfo and requestInfo are handled) and maintains full backwards compatibility.

Implementation Notes:

• All transport implementations follow the same pattern for consistency
• Testing focused on InMemoryTransport as it covers the core functionality
• Manual testing confirmed the feature works correctly with SSE and Streamable HTTP in production scenarios

Future Enhancements:

• Consider adding TypeScript generics for type-safe custom context (would require broader changes)
• Add integration tests for all transport types
• Update documentation with custom context examples

[dr3s]

One thing I had also addressed in a similar way was dependency injection. Is this PR intending to limit the context to data or support request locals generally that can be used for db connections etc...?

[grimmerk]

One thing I had also addressed in a similar way was dependency injection. Is this PR intending to limit the context to data or support request locals generally that can be used for db connections etc...?

@dr3s The current implementation passes an optional JS object with a Record<string, unknown> type as the custom context, allowing it to be used as a data context or for other JS objects (as property value), such as a DB connection object.

[dr3s]

@grimmerk the reason I asked is because I had tried using RequestHandlerExtra in this way but switched back to closures because it seems some code expected it to just be data. Do you think there's any concern using it for request scoped dependencies?

I tried using a generics approach to improve typesafe access to dependencies but was challenged by support in the sdk and RequestHandlerExtra

[grimmerk]

@dr3s I do not have any specific concerns for the case of request-scoped dependencies yet. I think it should work well.

Yes, adding generic is great. However, I have not tried it yet, as it requires more changes, and I'd like to make a PR smaller.

[grimmerk]

We can consider adding a generic in this PR (or new PRs) if more people think it would help. cc @ihrpr @pcarleton
e.g.

transport.setCustomContext<CustomContextForDB>({
  db: DBContextObj
});


// Access in tool handler
server.tool('search', async ({ query }, extra) => {
  // it would be inferred as CustomContextForDB type
  const dbContextObj = extra.customContext
});

[dr3s]

@grimmerk I like smaller PRs too. More of a question of whether this should be considered in the design.

[grimmerk]

Hi @cliffhall, @domdomegg , @ihrpr, this PR adds custom context support for MCP transports, enabling passing additional context (e.g., user info) to tool handlers - a very common need that currently requires workarounds like closures. Would appreciate a review when you have time. Thanks!

[cliffhall]

Hi @cliffhall, @domdomegg , @ihrpr, this PR adds custom context support for MCP transports, enabling passing additional context (e.g., user info) to tool handlers - a very common need that currently requires workarounds like closures. Would appreciate a review when you have time. Thanks!

@grimmerk I do like the looks of this, but I'd also like to see it running in an actual server.

Could you add an example server in examples/server and a repl in examples/client that exercises this feature? See the simpleStreamableHttp.ts files in both folders to see what I'm after.

If it is merged, people will need to see how it works, and seeing how it works would be a big help in deciding if it's a good feature to add.

[grimmerk]

@cliffhall, thanks for the kind review and feedback.

I've added feat: Add custom context example implementation to demonstrate what you suggest. Please let me know if it works.

[grimmerk]

Hi @cliffhall, @ihrpr, I've enhanced the example with clearer documentation on applying custom context to both API keys and MCP access tokens. I've also updated the PR description to better clarify the use cases.

Also wanted to mention that the Python SDK seems to have the same limitation. If this TypeScript implementation goes well, I'd be happy to contribute a similar solution for Python in the future.

Please take a look when you have time. Thanks!