# Mcplex

> MCPlex — the MCP backplane that unifies your AI agentic tools into one discoverable server.

- **Type:** MCP server
- **Install:** `agentstack add mcp-deghosal-2026-mcplex`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [deghosal-2026](https://agentstack.voostack.com/s/deghosal-2026)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [deghosal-2026](https://github.com/deghosal-2026)
- **Source:** https://github.com/deghosal-2026/mcplex
- **Website:** https://github.com/deghosal-2026/mcplex

## Install

```sh
agentstack add mcp-deghosal-2026-mcplex
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# MCPlex

[](.github/workflows/ci.yml)
[](LICENSE)
[](https://www.python.org/)
[](https://pypi.org/project/mcplex/)
[](https://github.com/astral-sh/ruff)
[](https://github.com/python/mypy)
[](CODE_OF_CONDUCT.md)
[](https://www.bestpractices.dev/projects/13801)

> 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](#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.4.0)

| What works | What's planned |
|---|---|
| `GET` with query params + `POST` with JSON body | `PUT` / `DELETE` support |
| Flat `param_mapping` (MCP arg → HTTP param) | Path-param templating (`/api/{id}`) |
| JSON + non-JSON response handling (HTML/text wrapped) | |
| Static header injection with `${ENV_VAR}` interpolation | OAuth 2.0 / OIDC |
| SSE heartbeat keepalive | Progress streaming, session continuity |
| Identity propagation (X-MCP-Client-Name / Version headers) | |
| Schema/argument validation (type, required, enum, min/max) | |
| Rate limiting per-tool/per-agent | |
| Structured audit logging (session_id, user_id, backend_url, etc.) | |
| Connection pooling (shared httpx.AsyncClient) | |
| 75 unit + integration tests | Write-tool approval flow |
| | Config hot-reload |

## 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:

| Accept header | Response format |
|---------------|-----------------|
| `application/json` | JSON-RPC over HTTP POST |
| `text/event-stream` | Server-Sent Events (one-shot framing) |

## 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`):

| Connector | Sibling Repo | Status |
|-----------|-------------|--------|
| guardian | [ai-code-guardian](https://github.com/deghosal-2026/ai-code-guardian) | Real backend with MCP API adapter |
| ci-agent | [ci-doctor](https://github.com/deghosal-2026/ci-doctor) | Real backend with MCP API adapter |
| sprintsense | [sprint-intelligence](https://github.com/deghosal-2026/sprint-intelligence) | Real backend with MCP API adapter |
| incident-commander | [ai-incident-commander](https://github.com/deghosal-2026/ai-incident-commander) | CLI-only; uses test-bench mock via `incidentgpt.py` native connector |

**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

```bash
pip install mcplex-backplane

# 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:

| Connector | Repo | Tools |
|-----------|------|-------|
| guardian | [ai-code-guardian](https://github.com/deghosal-2026/ai-code-guardian) | `guardian_check_policy`, `guardian_get_coverage` |
| ci-agent | [ci-doctor](https://github.com/deghosal-2026/ci-doctor) | `ci_diagnose_failure`, `ci_get_pipeline_history` |
| sprintsense | [sprint-intelligence](https://github.com/deghosal-2026/sprint-intelligence) | `dora_get_metrics`, `dora_get_trend` |
| incident-commander | [ai-incident-commander](https://github.com/deghosal-2026/ai-incident-commander) | `incident_query_active`, `incident_query_history`, `incident_get_timeline` |

## Docs

| Doc | Description |
|-----|-------------|
| [Architecture](docs/architecture.md) | System design, data flow, design decisions |
| [Deployment Guide](docs/deployment.md) | Production deployment, nginx config, security |
| [Troubleshooting](docs/troubleshooting.md) | Common errors and resolution steps |
| [Integration Guide](docs/integration/README.md) | How to connect repos via MCP API adapters |
| [Specification](docs/spec/mcplex.md) | Architecture, transport, connector design |
| [PRD](docs/prd/mcplex.md) | Product requirements and user stories |
| [Sprint Plan (WBS)](docs/wbs/mcplex.md) | Work breakdown and epics |
| [Config Reference](docs/config-reference.md) | YAML schema for connectors |
| [E2E Test Plan & Results](tests/e2e/README.md) | Test plan, 9/9 results, 15 screenshots |
| [Code Review](docs/review.md) | Internal code review |

## 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

**Shipped (v0.4.0)**
- Identity propagation (X-MCP-Client-Name / Version headers)
- Structured audit logging (session_id, user_id, backend_url, http_status)
- Per-tool / per-agent rate limiting
- Schema/argument validation (type, required, enum, min/max)
- Non-JSON response handling (HTML/text wrapped)
- SSE heartbeat keepalive
- Connection pooling (shared httpx.AsyncClient)
- 75 tests (unit + integration), self-contained mock-based integration tests
- PyPI publish as `mcplex-backplane`
- See [CHANGELOG.md](CHANGELOG.md) for full details

**Future (v1.0.0)**
- Write‑tool approval flow
- Config hot‑reload
- Path‑param templating (`/api/{id}`)
- PUT/DELETE support
- SSE progress streaming and session continuity
- OAuth 2.0 / OIDC

## License

MIT

## Resources

- **Issues:** [github.com/deghosal-2026/mcplex/issues](https://github.com/deghosal-2026/mcplex/issues) — bug reports and feature requests
- **Security:** [SECURITY.md](SECURITY.md) — report vulnerabilities privately
- **Contributing:** [CONTRIBUTING.md](CONTRIBUTING.md) — coding standards and PR process
- **Changelog:** [CHANGELOG.md](CHANGELOG.md) — release history

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [deghosal-2026](https://github.com/deghosal-2026)
- **Source:** [deghosal-2026/mcplex](https://github.com/deghosal-2026/mcplex)
- **License:** MIT
- **Homepage:** https://github.com/deghosal-2026/mcplex

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-deghosal-2026-mcplex
- Seller: https://agentstack.voostack.com/s/deghosal-2026
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.