MCPlex

Early proof-of-concept: a YAML-configured MCP proxy that maps simple JSON REST endpoints (GET + query params, POST + JSON body) into MCP tools. Not production-hardened — see Roadmap.

MCPlex sits between AI coding agents (Claude Code, Cursor, Codex) and your backend REST APIs. Agents discover tools via the standard MCP tools/list handshake and call them via tools/call. MCPlex translates those calls into HTTP requests to your backend. Zero LLM logic, zero model dependencies, ~400 lines of Python.

What It's Meant to Do

Most engineering teams have a graveyard of internal tools built before AI coding agents existed — CLIs, dashboards, webhook receivers, internal REST APIs. These tools work. They have users, auth, governance, and business logic baked in. What they don't have is an interface that AI agents can call.

MCPlex gives those tools a 2nd life. You don't rewrite them. You add a thin REST adapter if they don't already expose JSON (about 40 lines), point MCPlex at it with a YAML connector, and now any MCP-compatible agent can call them. The tool keeps its auth, its logic, its governance. MCPlex is just the new front door.

The key idea: connectors are YAML, not Python (for the 80% case where the backend already speaks JSON REST). Adding a new HTTP tool means adding a few lines of config — method, URL path, parameter mapping. The generic HTTP proxy handler does the rest.

The repo includes a 4-connector demo config as an illustration of the pattern — 3 connectors proxy to real sibling repos; the 4th runs on mock data via a native Python connector for backends without an HTTP server.

Current Limitations (v0.3.0)

What It Is Not

• Not an AI framework. MCPlex contains zero LLM calls, zero prompts, zero model dependencies. It is a pure HTTP proxy.
• Not an MCP SDK. MCPlex implements the MCP wire protocol directly. Backend tools never import an MCP library or add an MCP dependency.
• Not a replacement for backend APIs. MCPlex does not transform data or add business logic. It proxies calls to your existing REST endpoints.

Architecture

                    config.yaml
                         │
              ┌──────────▼──────────┐
              │  Tool Registry      │
              │  name → route       │
              └──────────┬──────────┘
                         │
              ┌──────────▼──────────┐
              │  HTTP Proxy Handler │
              │  (generic — reads   │
              │   method, path,     │
              │   param_mapping     │
              │   from config)      │
              └────┬────┬────┬──────┘
                   │    │    │
             ┌─────▼┐ ┌▼───┐┌▼────┐
             │ API A│ │API B││API C│
             └──────┘ └────┘└─────┘

1. On startup, MCPlex reads config.yaml, interpolates ${ENV_VAR} patterns, and builds a tool registry.
2. Each type: http connector generates an async proxy handler.
3. An agent connects and calls tools/list — MCPlex returns the catalog.
4. The agent calls tools/call — MCPlex validates arguments against the declared JSON Schema, maps MCP parameters to HTTP parameters, and makes the request.
5. The backend response is returned as an MCP tool result, with isError set when the tool fails.

Two transport modes, auto-detected by the Accept header:

What Is In This Repo

• MCPlex proxy server (Starlette, JSON-RPC, SSE transport)
• YAML config system (Pydantic models, env-var interpolation, config validation)
• Generic HTTP proxy handler (GET/POST with param mapping)
• Native Python connector fallback (incidentgpt.py) for backends without an HTTP server
• Test bench (mock server simulating all 4 backends)
• 50 unit tests, CI (lint, typecheck, test)

What Is NOT In This Repo (Sibling Repos)

The 4 demo connectors proxy to sibling repos. These must be cloned alongside mcplex for the full Docker Compose stack (see docker-compose.yml):

Total: 9 MCP tools across 4 demo connectors (3 real repos + 1 test-bench mock).

To try it without cloning sibling repos, run the test bench: python tests/test_bench.py.

Quick Start

pip install mcplex

# Try with the test-bench mock (no sibling repos needed)
python tests/test_bench.py &
mcplex serve --config config.yaml

# Or use docker-compose for the full stack
cp .env.example .env
docker compose up

Connect Claude Code: claude --mcp http://localhost:8000/mcp

Included Connectors

The demo config.yaml includes 4 connectors — 3 proxy to real sibling repos, 1 runs on the test-bench mock:

Docs

Roadmap

Shipped (v0.3.0)

• Generic HTTP proxy connector (YAML-driven, GET/POST)
• JSON-RPC + one-shot SSE framing (auto-detect by Accept header)
• Config validation (required base_url, env-var interpolation)
• isError flag on failed tool calls (MCP spec compliance)
• JSON-RPC batch request handling
• 4-connector demo config
• OSS readiness: CI, issue templates, CODE_OF_CONDUCT, SECURITY.md, CONTRIBUTING.md
• 50 unit tests, Docker Compose deployment

Future (v1.0.0)

• Identity propagation — carry user/agent identity through proxy
• Write‑tool approval flow
• Structured audit logging — timestamp, session, tool, params, latency, status
• Per‑tool / per‑agent rate limiting
• Config hot‑reload
• Path‑param templating, non‑JSON response handling, PUT/DELETE support
• SSE keepalive and progress streaming
• PyPI publish

License

MIT