MCP Manager

A development scaffold for managing multiple MCP servers behind one standard MCP gateway. The first catalog entry is the open-source Arxiv MCP server.

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

Agent harness
    |
    | Streamable HTTP MCP
    v
Gateway (tool discovery, namespacing, routing)
    |
    v
Runtime supervisor (startup, timeout, retry, cleanup)
    |
    | stdio MCP
    v
Arxiv MCP server
    |
    v
arXiv and related upstream APIs

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

Components

Component	Location	Responsibility
Server catalog	catalog/servers/	Declarative, one-file-per-server definitions.
Profiles	profiles/	Select servers and allow/deny tools for a workload.
Configuration	src/mcp_manager/config/	Typed manifest models and YAML loading.
Secrets	src/mcp_manager/secrets/	Resolve explicit secret references without writing resolved config.
Runtime	src/mcp_manager/runtime/	Launch and supervise backend MCP connections.
Gateway	src/mcp_manager/gateway/	Expose namespaced tools and route calls to backends.
Agent interface	src/mcp_manager/harness/	Framework-neutral interface and remote MCP client adapter.

See docs/ARCHITECTURE.md for the design boundaries.

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.

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

An MCP client can then connect 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.

Agent-harness integration

Agent frameworks should depend on AgentToolProvider, not the runtime or gateway implementation:

from mcp_manager.harness import GatewayMCPClient

async with GatewayMCPClient("http://127.0.0.1:8080/mcp") as tools:
    definitions = await tools.list_tools()
    result = await tools.call_tool(
        "arxiv__search_papers",
        {"query": "mixture of experts", "max_results": 3},
    )

The model API key belongs in the agent process. Service credentials belong in backend MCP subprocess environments and are resolved through secretRef.

Current scope

• One stdio backend: Arxiv.
• Tool discovery and calls only.
• One static profile.
• Environment-backed secret provider interface, unused by Arxiv.
• No persistence, 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.