MCP BridgeKit
Turn any MCP stdio server into a production HTTP API your web app can call.
Per-user session pooling · real timeout handling with background-job fallback · fail-closed auth · live dashboard
Potencialize seu agente
Instalação do publicador. Não é um endpoint do PlugMCP.
Host a copy with our keys and logs.
Ainda não há uma versão empacotada no registro. Siga o README do repositório.
URL remota ou um comando na sua máquina? Como as duas instalações diferem
Rodar no PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
AbrirDo publicador
Turn any MCP stdio server into a production HTTP API your web app can call.
Per-user session pooling · real timeout handling with background-job fallback · fail-closed auth · live dashboard
Turn any MCP stdio server into a production HTTP API: per-user session pooling, timeout survival via background jobs, fail-closed auth, SSE/webhook push, live dashboard. Python 3.11+ · FastAPI · Redis
Your Web App ──HTTP──▶ MCP BridgeKit ──stdio──▶ MCP Server (tool)
(React, Next.js, pooling · timeouts · (python, node, npx …)
mobile, backend) jobs · auth · dashboard
git clone https://github.com/mkbhardwas12/mcp-bridgekit.git && cd mcp-bridgekit
export MCP_BRIDGEKIT_API_KEY=$(openssl rand -hex 32)
docker compose up -d # Redis + API + 3 workers
curl -s -H "X-API-Key: $MCP_BRIDGEKIT_API_KEY" localhost:8000/tools/demo | jq .tools[].name
# "analyze_data"
curl -s -N -H "X-API-Key: $MCP_BRIDGEKIT_API_KEY" -H 'Content-Type: application/json' \
-d '{"user_id":"demo","messages":[],"tool_name":"analyze_data","tool_args":{"query":"Q4 revenue"}}' \
localhost:8000/chat
# data: {"content":[{"type":"text","text":"..."}], ...} ← streamed over SSE
# …or, if the tool runs >25s: data: {"status":"queued","job_id":"…"} → GET /job/{id} or SSE /mcp/events/{id}
Open http://localhost:8000/dashboard for live sessions, jobs, logs and tools.
MCP (Model Context Protocol) is an open standard that lets AI applications connect to external tools and data sources. MCP servers communicate over stdio (stdin/stdout) — which means they run as local subprocesses and speak JSON-RPC over pipes.
The problem: Web applications (React, Next.js, Vue, mobile apps) can't spawn local subprocesses. They only speak HTTP. There's a protocol mismatch.
MCP BridgeKit is the bridge. It sits between your web app and MCP stdio servers, translating HTTP requests into stdio subprocess calls and streaming results back:
Your Web App ──HTTP──▶ MCP BridgeKit ──stdio──▶ MCP Server (tool)
(this project)
Think of it as "nginx for MCP tools" — a reverse proxy that makes stdio tools available over HTTP.
Scenario: You're building a customer support chatbot in React. The AI can call tools like
search_docs,create_ticket,check_order_status— all implemented as MCP servers.
React App → POST /chat {tool: "search_docs", args: {query: "refund policy"}}
← SSE stream with search results
BridgeKit manages one MCP server process per conversation, so each user has isolated state.
Scenario: Your SaaS lets customers connect their own MCP tools (data analysis, code generation, API integrations). Each customer uses different tools.
Customer A → POST /chat {user_id: "cust-A", mcp_config: {command: "python", args: ["their_tool.py"]}}
Customer B → POST /chat {user_id: "cust-B", mcp_config: {command: "node", args: ["their_tool.js"]}}
Each customer gets a dedicated session with their own MCP server. Pool manages up to 100 concurrent sessions with automatic eviction.
Scenario: An MCP tool runs complex SQL queries or ML inference that takes 45 seconds. Your frontend uses Vercel with a 30-second timeout.
Client → POST /chat {tool: "run_analysis", args: {dataset: "sales_2025"}}
← SSE: {status: "queued", job_id: "abc-123"}
# 45 seconds later...
Client → GET /job/abc-123
← {status: "completed", result: {revenue: 4200000, growth: "12%"}}
BridgeKit's asyncio.timeout(25s) catches the slow call, queues it via Redis/RQ, and a background worker completes it.
Scenario: Your team has MCP tools for database queries, log analysis, and deployment — you want a single HTTP API to access all of them.
# Query production database
curl -X POST localhost:8000/chat \
-d '{"user_id": "dev-1", "tool_name": "query_db", "tool_args": {"sql": "SELECT count(*) FROM users"}}'
# Check which tools are available
curl localhost:8000/tools/dev-1
Run docker-compose up and all your tools are accessible from any HTTP client.
Scenario: A Slack bot, Zapier workflow, or n8n pipeline needs to call MCP tools based on triggers.
Slack Event → Zapier → POST /chat {tool: "summarize", args: {text: "..."}}
← {result: "Here's the summary..."}
BridgeKit is a standard HTTP API — any integration platform can call it.
Scenario: An iOS/Android app needs to call MCP tools but can't run subprocesses on the device.
Mobile App → POST https://your-server.com/chat
← SSE stream or job_id for polling
Deploy BridgeKit on your server, and mobile clients communicate over HTTPS.
graph LR
subgraph Clients
A[🌐 Web Chatbot]
B[⌨️ CLI / Script]
C[🔗 Third-party API]
end
subgraph BridgeKit
D[🚀 FastAPI Server\napp.py]
E[⚡ BridgeKit Core\ncore.py]
F[📊 Dashboard\ndashboard.py]
end
subgraph Backend
G[🧠 MCP Server\nstdio process]
H[(💾 Redis)]
I[👷 RQ Worker\nworker.py]
end
A -- POST /chat --> D
B -- POST /chat --> D
C -- POST /chat --> D
A -. GET /dashboard .-> F
D --> E
E -- stdio --> G
G -- stdout --> E
E -. timeout? .-> H
H --> I
I -- stdio --> G
I -- store result --> H
E -. poll result .-> H
style E fill:#10b981,stroke:#059669,color:#fff
style H fill:#f59e0b,stroke:#d97706,color:#fff
style D fill:#3b82f6,stroke:#2563eb,color:#fff
style G fill:#8b5cf6,stroke:#7c3aed,color:#fff
style I fill:#a855f7,stroke:#9333ea,color:#fff
sequenceDiagram
participant Client
participant FastAPI
participant BridgeKit as BridgeKit Core
participant MCP as MCP Server
participant Redis
participant Worker as RQ Worker
Client->>FastAPI: POST /chat {user_id, tool_name, tool_args}
FastAPI->>BridgeKit: bridge.call(req)
BridgeKit->>BridgeKit: Get/create session (per-user lock)
BridgeKit->>MCP: call_tool(name, args) with asyncio.timeout(25s)
alt ✅ Completes within timeout
MCP-->>BridgeKit: Tool result
BridgeKit-->>FastAPI: SSE: data: {result}
FastAPI-->>Client: Stream response
else ⏱ Timeout exceeded
BridgeKit->>Redis: Enqueue job + set status=queued
BridgeKit-->>FastAPI: SSE: {status: queued, job_id}
FastAPI-->>Client: Return job_id
Worker->>Redis: Pick up job
Worker->>MCP: Spawn session + call_tool
MCP-->>Worker: Result
Worker->>Redis: Store result + set status=completed
Client->>FastAPI: GET /job/{job_id}
FastAPI->>Redis: Get status + result
Redis-->>FastAPI: {status: completed, result: ...}
FastAPI-->>Client: Return result
end
user_id gets its own MCP stdio processasyncio.timeout() wraps every tool call — if it exceeds the threshold, the call is automatically queued as a background job via Redis/RQGET /job/{job_id} to check status/resultsGET /tools/{user_id} lists available tools from the MCP serverDELETE /session/{user_id}X-API-Key header protection — required by default; opt out only with ALLOW_NO_AUTH=trueDEFAULT_MCP_COMMAND plus anything in ALLOWED_MCP_COMMANDSGET /metrics in Prometheus exposition format — scrape with any monitoring stackerror_code (e.g. TOOL_CALL_FAILED, RATE_LIMITED)GET /mcp/events/{job_id} — browser/client listens in real-time, stream closes automatically on completion# Clone & install
git clone https://github.com/mkbhardwas12/mcp-bridgekit.git
cd mcp-bridgekit
# Copy environment config
cp .env.example .env
# REQUIRED: set an API key (protected endpoints return 401 until you do)
echo "MCP_BRIDGEKIT_API_KEY=$(openssl rand -hex 32)" >> .env
# Install (pick one)
uv sync --dev # recommended — fastest
pip install -e ".[dev]" # alternative
# Start Redis (required for job queue)
docker run -d -p 6379:6379 redis:7-alpine
# Terminal 1 — Run the server
uvicorn mcp_bridgekit.app:app --reload
# Terminal 2 — Start the background worker
mcp-bridgekit-worker
Open:
graph TB
subgraph Docker Compose
R[(Redis\nredis:7-alpine\nport 6379)]
S[BridgeKit Server\npython:3.12-slim\nport 8000]
W[RQ Worker\npython:3.12-slim]
end
Internet((Internet)) -->|:8000| S
S --> R
W --> R
style R fill:#ef4444,stroke:#dc2626,color:#fff
style S fill:#3b82f6,stroke:#2563eb,color:#fff
style W fill:#8b5cf6,stroke:#7c3aed,color:#fff
export MCP_BRIDGEKIT_API_KEY=$(openssl rand -hex 32) # or put it in .env
docker-compose up
This starts Redis, the BridgeKit server (port 8000), and 3 RQ worker replicas. Compose refuses to start without MCP_BRIDGEKIT_API_KEY.
By default the API is bound to 127.0.0.1 only. To expose it (behind TLS / a reverse proxy):
MCP_BRIDGEKIT_BIND=0.0.0.0 docker-compose up
Click the button above to deploy your own instance. You'll need:
MCP_BRIDGEKIT_REDIS_URL and MCP_BRIDGEKIT_API_KEY (e.g. openssl rand -hex 32) during setupNote: Vercel's 30s function timeout is exactly why BridgeKit exists — any MCP tool call exceeding 25s is automatically queued as a background job. Your users get a
job_idinstantly and poll for results.
POST /chatCall an MCP tool. Returns SSE stream. Auto-queues on timeout.
{
"user_id": "user-123",
"messages": [{"role": "user", "content": "analyze sales data"}],
"tool_name": "analyze_data",
"tool_args": {"query": "Q4 revenue trends"},
"mcp_config": {"command": "python", "args": ["examples/mcp_server.py"]}
}
mcp_config is optional (defaults to DEFAULT_MCP_COMMAND/DEFAULT_MCP_ARGS). command must be in the allowlist — anything else returns HTTP 400 COMMAND_NOT_ALLOWED. Only command and args are accepted.
GET /job/{job_id}Poll background job status. Returns queued, running, completed (with result), or failed.
GET /tools/{user_id}List available tools from the server's default MCP server (DEFAULT_MCP_COMMAND / DEFAULT_MCP_ARGS).
DELETE /session/{user_id}Close a user's MCP session.
GET /healthHealth check with stats: active sessions, total requests, errors, queued jobs, known tools.
GET /metricsPrometheus-compatible metrics in text exposition format. Safe to scrape without auth.
bridgekit_active_sessions 3
bridgekit_requests_total 472
bridgekit_errors_total 2
bridgekit_queued_jobs 1
...
Configure Prometheus:
scrape_configs:
- job_name: mcp-bridgekit
static_configs:
- targets: [bridgekit:8000]
metrics_path: /metrics
GET /mcp/events/{job_id} (v0.9)Server-Sent Events stream. Connect after submitting a long job; fires one event when the background job completes, then closes automatically. No auth required.
const es = new EventSource(`/mcp/events/${jobId}`);
es.onmessage = (e) => {
const data = JSON.parse(e.data);
if (data.status === 'completed') {
console.log('Job done!', data.result);
es.close();
}
};
Event payload:
{
"job_id": "abc-123",
"status": "completed",
"result": { ... },
"user_id": "user-456",
"completed_at": "2026-02-23T12:00:00+00:00"
}
All error payloads include a structured error_code field:
{ "status": "error", "error_code": "TOOL_CALL_FAILED", "message": "...", "attempts": 3 }
{ "status": "queued", "error_code": "TOOL_TIMED_OUT", "job_id": "..." }
graph TD
R1[Request user-abc] --> GL
R2[Request user-abc] --> GL
R3[Request user-xyz] --> GL
GL[🔒 Global Lock\nheld for nanoseconds]
GL -->|get/create| UL1[🔑 Lock: user-abc]
GL -->|get/create| UL2[🔑 Lock: user-xyz]
UL1 -->|serialize| S1[Session: user-abc\nMCP stdio process]
UL2 -->|serialize| S2[Session: user-xyz\nMCP stdio process]
S1 --> POOL[(Session Pool\nTTL: 3600s\nEviction: oldest)]
S2 --> POOL
style GL fill:#ef4444,stroke:#dc2626,color:#fff
style UL1 fill:#f59e0b,stroke:#d97706,color:#fff
style UL2 fill:#f59e0b,stroke:#d97706,color:#fff
style POOL fill:#10b981,stroke:#059669,color:#fff
Set via environment variables or .env file (prefix: MCP_BRIDGEKIT_):
Auth is fail-closed: with no API_KEY configured, protected endpoints return HTTP 401 AUTH_NOT_CONFIGURED.
Set MCP_BRIDGEKIT_ALLOW_NO_AUTH=true only on trusted private networks.
Protects /chat, /tools/, /job/, and /session/ endpoints.
/health, /metrics, and /dashboard stay public for monitoring tools.
# Generate and set a key
export MCP_BRIDGEKIT_API_KEY=$(openssl rand -hex 32)
# All protected calls need the header
curl -X POST http://bridgekit:8000/chat \
-H "X-API-Key: your-secret-key" \
-H "Content-Type: application/json" \
-d '{...}'
Without the key (or with wrong key): HTTP 401 with error_code: MISSING_API_KEY or INVALID_API_KEY.
mcp_config.command is validated against an allowlist before any subprocess is spawned.
By default only DEFAULT_MCP_COMMAND is allowed; extend it explicitly:
export MCP_BRIDGEKIT_ALLOWED_MCP_COMMANDS='["node", "npx"]'
Requests naming any other command get HTTP 400 COMMAND_NOT_ALLOWED. mcp_config accepts only command and args — extra fields (env, cwd, …) are rejected with 422.
Per-user fixed-window rate limiting backed by Redis. Rejects excess requests with HTTP 429.
# Default: 60 requests per user_id per minute
export MCP_BRIDGEKIT_RATE_LIMIT_PER_MINUTE=60
# Disable entirely
export MCP_BRIDGEKIT_RATE_LIMIT_PER_MINUTE=0
Transient tool-call failures (e.g. subprocess crash) are automatically retried.
# Default: 2 retries — waits 1s, then 2s between attempts
export MCP_BRIDGEKIT_MAX_TOOL_RETRIES=2
# Disable retries
export MCP_BRIDGEKIT_MAX_TOOL_RETRIES=0
Note: TimeoutError is never retried — it immediately queues as a background job.
Added in v0.9.0. Instead of polling GET /job/{job_id}, get instant push when a background job finishes.
BridgeKit POSTs the result to your configured URL when any background job completes.
export MCP_BRIDGEKIT_WEBHOOK_URL=https://your-api.example.com/webhook/mcp
Payload your endpoint receives:
{
"job_id": "abc-123",
"status": "completed",
"result": { ... },
"user_id": "user-456",
"completed_at": "2026-02-23T12:00:00+00:00"
}
Webhook failures are caught and logged — they never crash the worker.
Your frontend holds open a Server-Sent Events connection. The stream closes automatically after the completion event.
// After POST /chat returns {status: "queued", job_id: "abc-123"}
const es = new EventSource(`/mcp/events/abc-123`);
es.onmessage = (e) => {
const data = JSON.parse(e.data);
if (data.status === 'completed') {
renderResult(data.result);
es.close();
}
};
SSE uses Redis Pub/Sub internally, so it works correctly when the API server and RQ worker are in separate processes/containers.
# Your AWS Lambda / FastAPI endpoint
@app.post("/api/v1/analyze")
async def analyze(req: BridgeRequest):
result = await bridge.call(req)
if result.status == "queued":
return {
"status": "queued",
"job_id": result.job_id,
"sse_url": f"https://bridgekit.yourdomain.com/mcp/events/{result.job_id}"
}
return result
Disable either channel independently:
MCP_BRIDGEKIT_ENABLE_SSE=false # turn off SSE, keep webhook
MCP_BRIDGEKIT_WEBHOOK_URL= # leave empty to disable webhook
BridgeKit works with any MCP server — you just pass different mcp_config values.
The mcp_config tells BridgeKit which command to spawn:
import httpx
BRIDGEKIT_URL = "http://your-bridgekit-host:8000"
# Step 1: Discover available tools
resp = await httpx.AsyncClient().get(
f"{BRIDGEKIT_URL}/tools/discovery",
params={"command": "npx", "args": "-y,@aws/aws-mcp"},
)
print(resp.json()) # Shows all tools with schemas
# Step 2: Call a tool
async with httpx.AsyncClient(timeout=60.0) as client:
resp = await client.post(f"{BRIDGEKIT_URL}/chat", json={
"user_id": "user-123",
"messages": [{"role": "user", "content": "list instances"}],
"mcp_config": {
"command": "npx",
"args": ["-y", "@aws/aws-mcp"],
},
"tool_name": "describe_instances",
"tool_args": {"region": "us-east-1"},
})
Prerequisites: Install the MCP server package on the BridgeKit host (npm install -g @aws/aws-mcp) and configure AWS credentials.
Full guide: See docs/INTEGRATION_GUIDE.md for deployment on AWS, credential setup, polling for long-running jobs, and complete working examples.
Code examples: See examples/aws_integration.py for 8 ready-to-use endpoint patterns.
from fastapi import FastAPI
from mcp_bridgekit import BridgeKit, BridgeRequest
app = FastAPI()
bridge = BridgeKit()
@app.post("/chat")
async def chat(req: BridgeRequest):
return await bridge.call(req)
graph LR
subgraph src/mcp_bridgekit
APP[app.py\nFastAPI routes]
CORE[core.py\nBridgeKit engine ⚡]
CFG[config.py\npydantic-settings]
MDL[models.py\nPydantic models]
WRK[worker.py\nRQ worker]
DASH[dashboard.py\n/dashboard]
LAND[landing.py\n/ landing]
end
APP --> CORE
APP --> DASH
APP --> LAND
CORE --> CFG
CORE --> MDL
WRK --> CFG
style CORE fill:#10b981,stroke:#059669,color:#fff
style APP fill:#3b82f6,stroke:#2563eb,color:#fff
style WRK fill:#8b5cf6,stroke:#7c3aed,color:#fff
A TypeScript implementation is available in ts/. Same architecture — session pooling, timeout handling, Redis queueing.
cd ts && npm install && npm run build && npm start
Verify everything works with these steps:
# Option A — Docker (easiest)
docker-compose up --build
# Option B — Manual (3 terminals)
# T1: docker run -d -p 6379:6379 redis:7-alpine
# T2: mcp-bridgekit-worker
# T3: uvicorn mcp_bridgekit.app:app --reload --port 8000
Open http://localhost:8000/dashboard — should show 0 sessions, 0 jobs.
curl -N -X POST http://localhost:8000/chat \
-H "Content-Type: application/json" \
-d '{
"user_id": "test-001",
"messages": [{"role": "user", "content": "hello"}],
"tool_name": "analyze_data",
"tool_args": {"query": "test query"}
}'
→ SSE stream with result appears immediately. Dashboard shows 1 active session.
Edit examples/mcp_server.py — change asyncio.sleep(2) to asyncio.sleep(35), then re-run the curl above.
→ Immediate response: {"status": "queued", "job_id": "..."}
→ Dashboard updates live (Queued Jobs increases)
→ Worker terminal shows processing
curl http://localhost:8000/job/{job_id_from_step_4}
→ Returns {"status": "completed", "result": {...}} once the worker finishes.
curl "http://localhost:8000/tools/test-001"
curl -X DELETE http://localhost:8000/session/test-001
curl http://localhost:8000/health
→ Returns active sessions, request counts, error counts, queue depth.
Expected result: Tools respond instantly → slow tools get queued → dashboard shows live updates → sessions scale cleanly.
BridgeKit is designed to scale horizontally:
# Scale workers to 5 replicas
docker-compose up --scale worker=5
# Or run standalone workers on any machine
MCP_BRIDGEKIT_REDIS_URL=redis://shared-redis:6379 mcp-bridgekit-worker
See ARCHITECTURE.md for detailed diagrams and component docs. When running the server, visit /architecture for an interactive HTML version.
Issues and pull requests are welcome — see CONTRIBUTING.md. Every fix or hardening that lands is credited in CHANGELOG.md. To report a vulnerability privately, use GitHub's security advisories — details in SECURITY.md.
.dockerignore / .gitignore hardening (#1)MIT
Turn any MCP stdio server into a production HTTP API: per-user session pooling, timeout survival via background jobs, fail-closed auth, SSE/webhook push, live dashboard. Python 3.11+ · FastAPI · Redis
Ferramentas
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
Este registro não lista nenhuma variável de ambiente obrigatória.
MCP Bridgekit roda localmente via stdio.
Última verificação: 2026-10-28. Turn any MCP stdio server into a production HTTP API: per-user session pooling, timeout survival via background jobs, fail-closed auth, SSE/webhook push, live dashboard. Python 3.11+ · FastAPI · Redis