mcp-chain

MCP Chain is a composable middleware framework for building MCP server chains in Python. It sits between MCP clients and downstream servers as a transparent proxy, letting you transform requests and responses, add authentication, logging, or orchestrate multiple MCP calls behind the scenes. The framework exposes a functional chain API where each middleware layer can inspect or modify metadata and requests, then forward them to the next layer or a downstream MCP server.

To use it, you typically run the CLI or import the library in your Python project. The README demonstrates creating a chain with mcp_chain(), adding middleware via .then(), and starting a server with serve(). It also provides a built-in CLI server (CLIMCPServer) that exposes local tools as MCP capabilities and an ExternalMCPServer that forwards to downstream MCP endpoints. The tooling supports auto-detection of chain variables in Python files for quick setup and offers examples for authentication, request/response transformation, and multi-layer middleware stacks. You can mix and match middleware that operate on metadata (tools, descriptions) and on the request/response dictionaries themselves, returning transformed results to the client.

Practical use cases include adding authentication tokens, enriching tool metadata, injecting headers, logging traffic, and transforming multi-step tasks into single high-level MCP calls by combining multiple downstream requests in a single middleware layer.

Prerequisites:

• Python 3.8+ (or compatible Python runtime)
• Optional but recommended: pipx to install CLIs cleanly

Install via pip (recommended for quick setup):

pip install mcp-chain

Install the uvx-based CLI tooling (as shown in the Quickstart) to run an MCP Chain server without additional boilerplate:

pipx install uvx  # if you prefer pipx-based CLI exposure

Alternatively, run the server from a Python script by importing mcp_chain and serve, or install the package from source and run your own cli_server.py as demonstrated in the Quickstart.

Example quickstart flow:

# Ensure dependencies are installed
pip install mcp-chain

# Then run (as shown in README) with uvx
uvx mcp-chain cli_server.py

Tips and notes:

• This MCP server runs on Python and relies on the FastMCP SDK for protocol compliance. It is designed to be highly composable, so you can stack multiple middleware layers to transform both metadata and requests.
• The Quickstart demonstrates using a CLIMCPServer to expose local CLI tools as MCP capabilities and an ExternalMCPServer for downstream proxies. Use the .then() chaining to compose middleware and downstream servers.
• If you modify middleware that alters metadata, remember to return the updated metadata dict so downstream layers see the changes.
• Environment variables are optional but can be used to customize logging, port binding, or feature flags. Common options include setting a port, host, or enabling verbose logging.
• When running via uvx, the example uses: command uvx with args ["mcp-chain", "cli_server.py"]. You can adapt the args to point to your actual Python script that defines the MCP chain.
• If you encounter port conflicts or binding issues, verify the port you expose in serve() and ensure no other process is using it. Check firewall rules if exposing the service externally.
• The project emphasizes zero-serialization overhead in the chain by operating on Python dicts internally, which can simplify debugging but means you should keep dict structures consistent across middleware.