experimental-ext-interceptors

The experimental-ext-interceptors repository provides a reference implementation of the Model Context Protocol (MCP) interceptor extension. Its purpose is to prototype how interceptors can observe and modify MCP messages as they flow between MCP clients and services, enabling capabilities like validation, enrichment, routing decisions, or auditing. The project covers multi-language references (including a TypeScript-based interceptor package) to demonstrate how interceptors can be implemented and consumed in different language runtimes. To use the provided package, install the interceptor package in your environment and run it against your MCP-enabled stack. Once running, the interceptor can inspect inbound and outbound MCP messages, apply configurable rules, and forward messages to the next hop in your chain. The documentation and examples in this repo illustrate how to register interceptors, configure their behavior, and test their effects in a local development setup.

Prerequisites:

• Node.js (v18+) and npm installed on your machine
• Access to a shell with network connectivity to pull packages from npm or a local registry

Step-by-step:

1. Install Node.js if you don’t have it: download from https://nodejs.org/ and install.

2. In your project directory (or a temporary workspace), install the interceptor package:

   npm install -g @ext-modelcontextprotocol/interceptors

   Note: The package name reflects the TypeScript-based interceptor reference in this repository. If you prefer to use a local development version, you can link the package from the repository path after building it, or publish to a private registry as needed.

3. Run the interceptor server against your MCP deployment:

   npx -y @ext-modelcontextprotocol/interceptors

   You can also run it within your project without the -g/global install by using the npx invocation directly as shown above.

4. Verify that the MCP stack recognizes the interceptor and that the logs show the interceptor actively observing and/or modifying messages as configured.

Optional: If you are developing locally across languages (e.g., Python or Go implementations mentioned in the repo), follow the language-specific setup instructions within their respective folders (csharp/sdk, go/sdk, python/sdk, typescript/sdk) to run their examples in parallel with the TypeScript interceptor.

• This extension is labeled Experimental. Use it for prototyping and feedback rather than production use.
• The repository includes implementations and references across multiple languages; the TypeScript interceptor is the most ready for quick testing in a Node.js environment, while other language implementations are planned or in progress.
• Typical environment variables you may customize include MCP_ENDPOINT for the MCP gateway/endpoint, LOG_LEVEL for logging verbosity, and any interceptor-specific configuration (e.g., rule sets, transformation maps).
• If you encounter issues, confirm that the MCP endpoint is reachable from the interceptor host and that any required permissions or credentials are configured in your environment. Check CI workflow hints in the repository for language-specific troubleshooting steps.
• When testing, use clean environments or sandbox MCP instances to avoid unintended side effects in production-like stacks.