MCP Manager

A development scaffold for managing multiple MCP servers behind one standard MCP gateway. The default profile enables open-source Arxiv and calculator MCP servers.

This repository intentionally separates the components that MCP-Atlas and Toolathlon combine in different ways:

MCP client
    |
    | Streamable HTTP MCP
    v
Gateway (tool discovery, namespacing, routing)
    |
    v
Runtime supervisor (startup, timeout, retry, cleanup)
    |
    | stdio MCP
    +--> Arxiv MCP server --> arXiv and related upstream APIs
    |
    +--> Calculator MCP server
    |
    +--> Filesystem MCP server --> persistent data/ directory
    |
    +--> Local Weather MCP server --> WeatherAPI
    |
    | Streamable HTTP MCP + request-scoped API key
    +--> GitHub MCP server --> GitHub APIs
    |
    +--> Local Twelve Data MCP server --> Twelve Data APIs

This is a demo for further development. Dependencies and the Arxiv server are declared but are not vendored into this repository.

Components

See docs/ARCHITECTURE.md for the design boundaries.

Related MCP server: MCP Gateway

Arxiv backend

The catalog pins blazickjp/arxiv-mcp-server at 0.6.2 and launches it in an isolated uvx environment:

uvx --from arxiv-mcp-server==0.6.2 arxiv-mcp-server

The upstream server uses stdio by default and does not require an API key. Gateway-visible names are stable and namespaced, for example:

arxiv__search_papers
arxiv__get_abstract
arxiv__download_paper

The double-underscore name is stored in a routing table; the gateway never parses it to determine the backend.

Calculator backend

The catalog pins githejie/mcp-server-calculator at 0.2.0 and launches it with uvx plus a compatible mcp==1.28.1 pin. It exposes one gateway tool:

calculator__calculate

The tool accepts an expression string, for example 2 + 3 * 4.

Weather backend

The catalog integrates geobio/weather-mcp-server at commit 70b6a7c8183c8a3acc175f786f4b7be9c2ba66e4. The locally maintained service under services/weather-mcp-server/ runs as a persistent local stdio backend. The gateway starts it automatically, sends each client's key through the MCP tools/call _meta.apiKey field, and stops it when the gateway exits. One running child process can safely handle clients with different WeatherAPI keys.

Start only the gateway. Weather does not need an API key at startup and does not listen on a TCP port:

uv run mcp-manager --profile profiles/weather.yaml serve \
  --host 127.0.0.1 --port 8080

The client supplies its own key in MCP request metadata:

{"credentials":{"weather":{"apiKey":"<the client's WeatherAPI key>"}}}

The exposed tools are namespaced, including:

weather__weather_current
weather__weather_forecast
weather__weather_history
weather__weather_alerts
weather__weather_airquality
weather__weather_astronomy
weather__weather_search
weather__weather_timezone
weather__weather_sports

The gateway maps that credential to _meta.apiKey only on Weather MCP tool calls. The local service keeps it in a request-local variable and does not log it or store it in process-wide state.

With the Weather gateway running, test it using either client:

export WEATHER_API_KEY='<your-weatherapi-key>'
bash examples/test_weather_curl.sh
uv run python examples/test_weather_python.py

List the Weather tools and their parameter schemas without calling WeatherAPI:

uv run python examples/list_mcp_tools.py \
  --credential-env weather=WEATHER_API_KEY \
  --show-schema

GitHub backend

The catalog includes GitHub's hosted official MCP server at https://api.githubcopilot.com/mcp/. It is opt-in because it requires a GitHub personal access token and exposes repository data. The supplied profile enables GitHub's server-side read-only mode.

The gateway itself starts once, without a GitHub token, and remains running:

uv run mcp-manager --profile profiles/github.yaml serve \
  --host 127.0.0.1 --port 8080

Every client supplies its own credential in each relevant MCP request's params._meta object:

{"credentials":{"github":{"apiKey":"<the client's current token>"}}}

The gateway does not read a GitHub token from its environment. If client A connects with token A and client B later connects with token B, the same running gateway creates or reuses separate authenticated upstream GitHub MCP sessions for them. The client-facing gateway transport is stateless, so a token change takes effect on the next request without a gateway restart. How a client obtains its token (user input, its own secret store, an identity service, or another mechanism) is outside the gateway protocol.

The profile permits every tool made available by GitHub's server-side read-only mode; each token still determines which repositories its owner can see. Discovered tools use the github__ namespace. To intentionally enable GitHub write tools, change X-MCP-Readonly in catalog/servers/github.yaml to "false"; token permissions and profile argument policies still apply.

With the GitHub profile running, test the read-only github__get_me tool using either client:

export GITHUB_TOKEN='<your-github-token>'
bash examples/test_github_curl.sh
uv run python examples/test_github_python.py

Point either example at another Gateway deployment with MCP_URL for curl or --url for Python.

Twelve Data backend

The catalog uses the tools from the official mcp-server-twelve-data package at version 0.2.5. A small locally maintained adapter under services/twelve-data-mcp-server/ runs it as a persistent stdio backend. The adapter removes the startup -k requirement and reads each client's API key from the MCP tools/call _meta.apiKey field instead.

Start only the Gateway. The Twelve Data MCP Server starts automatically, does not listen on a TCP port, and does not receive an API key in its command line or environment:

uv run mcp-manager --profile profiles/twelvedata.yaml serve \
  --host 127.0.0.1 --port 8080

Each client sends its own raw Twelve Data API key in MCP request metadata:

{"credentials":{"twelvedata":{"apiKey":"<the client's Twelve Data API key>"}}}

The Gateway maps the value to _meta.apiKey only for the selected Twelve Data tool call. The long-running local Server reads it into a request-local variable and forwards it to api.twelvedata.com. Different clients and different keys can safely share the same Server process.

Discover the tools and their parameters using either example:

export TWELVE_DATA_API_KEY='<your-twelve-data-api-key>'
bash examples/test_twelvedata_curl.sh
uv run python examples/test_twelvedata_python.py

The adapter keeps the API key out of tool schemas and sanitizes upstream HTTP errors so credential-bearing URLs are not exposed to clients or logs.

Run Weather and Twelve Data together with one Gateway:

uv run mcp-manager --profile profiles/weather-twelvedata.yaml serve \
  --host 127.0.0.1 --port 8080

Then use both request-scoped credentials from one Python MCP session:

export WEATHER_API_KEY='<your-weatherapi-key>'
export TWELVE_DATA_API_KEY='<your-twelve-data-api-key>'
bash examples/test_weather_twelvedata_curl.sh
uv run python examples/test_weather_twelvedata_python.py

Both examples send both entries for tools/list, then send only weather for the Weather call and only twelvedata for the Twelve Data call.

Filesystem backend

The filesystem profile starts one persistent local @modelcontextprotocol/server-filesystem@2026.7.10 stdio process. Its only allowed directory is this repository's data/ directory. All Gateway clients using this profile share the same process and files; the Filesystem server rejects paths outside that directory.

Install Node.js 20 or newer for the current package, then start the Gateway:

proxy_on  # only when npm needs the configured network proxy
uv run mcp-manager --profile profiles/filesystem.yaml serve \
  --host 127.0.0.1 --port 8080

Test independent write and read requests using either client:

bash examples/test_filesystem_curl.sh
uv run python examples/test_filesystem_python.py

Client tool paths are relative to the allowed root. For example, filesystem-python-example.txt is stored on disk as data/filesystem-python-example.txt; clients should not prefix it with data/ again. The profile intentionally exposes both read and write tools and serializes calls with maxConcurrency: 1.

Server-scoped request credentials

Server manifests declare how a credential is injected. Remote HTTP servers can use Authorization: Bearer <token>; local stdio servers can use MCP request metadata such as _meta.apiKey. Profiles bind those server-specific slots to fixed tool and argument policies. Clients group credentials by catalog server name in params._meta:

{
  "_meta": {
    "credentials": {
      "weather": {"apiKey": "<weather-key>"},
      "twelvedata": {"apiKey": "<twelve-data-key>"}
    }
  }
}

The gateway selects only the entry matching the target tool's server and maps it to that backend's configured HTTP header or MCP request metadata. A tools/list request may carry several server entries, while each tools/call normally needs only one. Raw tokens remain in process memory. Authenticated remote MCP sessions are pooled by salted token fingerprint and closed after their configured idle timeout; local stdio servers receive the current key on each tool call.

Intended development commands

After installing Python 3.11+ and uv:

uv sync --extra dev
uv run mcp-manager list-servers
uv run mcp-manager doctor
uv run mcp-manager serve --host 127.0.0.1 --port 8080

For a credentialed multi-server profile, bind each server to an environment variable explicitly:

uv run mcp-manager --profile profiles/weather-twelvedata.yaml doctor \
  --credential-env weather=WEATHER_API_KEY \
  --credential-env twelvedata=TWELVE_DATA_API_KEY

An MCP-aware client connects to:

http://127.0.0.1:8080/mcp

The doctor command starts the selected backend, performs MCP initialization, and lists the tools that the gateway would expose.

Client tests

The gateway uses stateless Streamable HTTP with JSON responses. A JSON-RPC request can therefore call a tool directly without first obtaining an MCP session ID. Requests that expect a response must include an id; a JSON-RPC message without id is a notification and receives no tool result.

With the gateway running on port 8080, test a one-request curl tool call:

bash examples/test_mcp_curl.sh

Override the endpoint when needed:

MCP_URL=https://example.test/mcp bash examples/test_mcp_curl.sh

Test the official Python MCP client, including initialization, discovery, and a tool call:

uv run python examples/test_mcp_python.py

Or point it at another deployment:

uv run python examples/test_mcp_python.py --url https://example.test/mcp

List every discovered tool and its input parameters:

uv run python examples/list_mcp_tools.py

Include each tool's complete input JSON Schema:

uv run python examples/list_mcp_tools.py --show-schema

Use --url https://example.test/mcp to inspect another deployment.

Current scope

• Five local stdio backends (Arxiv, calculator, Filesystem, Weather, and Twelve Data) plus the hosted Streamable HTTP GitHub backend.

• Standard MCP tool discovery and calls through one gateway.

• Static default, Filesystem, Weather, GitHub, Twelve Data, and combined Weather/Twelve Data profiles.

• Static secret providers plus request-scoped, server-named API credentials in MCP _meta for API-backed servers.

• Files under data/ persist on disk; Gateway metadata itself has no persistent store, authentication, admin API, hot reload, or distributed state.

These omissions are deliberate so the repository remains a clear starting point rather than a prematurely complex platform.