MCP BridgeKit

Embeddable MCP stdio → HTTP bridge for web chatbots.

Turn any MCP stdio server into HTTP endpoints your web app can call. Per-user session pooling, real timeout handling with background job fallback, live dashboard.

What Is MCP BridgeKit?

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.

The Problem It Solves

| Challenge | Without BridgeKit | With BridgeKit | |-----------|-------------------|----------------| | Web app needs MCP tools | Can't — browsers can't spawn subprocesses | POST /chat with tool name and args | | Multiple users sharing tools | Each needs their own server setup | Per-user session pooling (up to 100 concurrent) | | Tool call takes 60 seconds | HTTP gateway timeout (Vercel 30s, CloudFlare 30s) | Auto-queues as background job, client polls GET /job/{id} | | Which tools are available? | Must read docs or hardcode | GET /tools/{user_id} — live discovery | | Monitoring & debugging | Blind — no visibility | Live dashboard: sessions, jobs, logs, tools | | Session cleanup | Zombie processes leak memory | Auto-eviction (TTL + pool limit) + manual DELETE /session/{id} |

Use Cases & Scenarios

1. AI Chatbot with Tool Calling

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.

2. Multi-Tenant SaaS Platform

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.

3. Long-Running Data Processing

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.

4. Internal Developer Tools

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.

5. Webhook / Integration Pipelines

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.

6. Mobile Applications

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.

When NOT to Use BridgeKit

| Scenario | Better Alternative | |----------|-------------------| | CLI tool calling MCP servers locally | Use MCP SDK directly — no HTTP needed | | MCP server already speaks HTTP (Streamable HTTP transport) | Connect directly — no bridge needed | | Single-user desktop app | MCP SDK + stdio directly |

Architecture

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

Request Flow

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

Key Features

Per-user sessions: Each user_id gets its own MCP stdio process
Real timeout handling: asyncio.timeout() wraps every tool call — if it exceeds the threshold, the call is automatically queued as a background job via Redis/RQ
Background job polling: GET /job/{job_id} to check status/results
Tool discovery: GET /tools/{user_id} lists available tools from the MCP server
Session management: Auto-eviction when pool is full, TTL-based expiry, manual DELETE /session/{user_id}
Live dashboard: HTMX + Tailwind — sessions, jobs, logs, tools (no build step)
Structured logging: via structlog
API key auth (v0.8): X-API-Key header protection — disabled by default, backward-compatible
Rate limiting (v0.8): Per-user fixed-window via Redis (default 60 req/min), returns HTTP 429
Retry with backoff (v0.8): Transient failures retried up to 2× with exponential backoff (1s, 2s)
Prometheus metrics (v0.8): GET /metrics in Prometheus exposition format — scrape with any monitoring stack
Structured error codes (v0.8): All errors include error_code (e.g. TOOL_CALL_FAILED, RATE_LIMITED)
Webhook push (v0.9): Worker POSTs job result to your URL when a background job completes
SSE push (v0.9): GET /mcp/events/{job_id} — browser/client listens in real-time, stream closes automatically on completion

Quickstart

# Clone & install
git clone https://github.com/mkbhardwas12/mcp-bridgekit.git
cd mcp-bridgekit

# Copy environment config
cp .env.example .env   # edit if needed (all vars have sensible defaults)

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

http://localhost:8000 — Landing page
http://localhost:8000/dashboard — Live dashboard
http://localhost:8000/docs — Interactive API docs

Docker (Recommended)

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

docker-compose up

This starts Redis, the BridgeKit server (port 8000), and 3 RQ worker replicas.

One-Click Deploy (Vercel)

Click the button above to deploy your own instance. You'll need:

A Redis instance (e.g., Upstash, Railway, or Redis Cloud)
Set the MCP_BRIDGEKIT_REDIS_URL environment variable during setup

Note: 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_id instantly and poll for results.

API Reference

`POST /chat`

Call 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"]}
}

`GET /job/{job_id}`

Poll background job status. Returns queued, running, completed (with result), or failed.

`GET /tools/{user_id}?command=python&args=examples/mcp_server.py`

List available tools from the MCP server.

`DELETE /session/{user_id}`

Close a user's MCP session.

`GET /health`

Health check with stats: active sessions, total requests, errors, queued jobs, known tools.

`GET /metrics`

Prometheus-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"
}

Error Response Format (v0.8.0+)

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": "..." }

| Error Code | Cause | |---|---| | SESSION_CREATE_FAILED | Could not spawn MCP server subprocess | | TOOL_CALL_FAILED | Tool raised an exception (after all retries) | | TOOL_TIMED_OUT | Tool exceeded timeout — job queued | | RATE_LIMITED | User exceeded requests-per-minute limit | | MISSING_API_KEY | Auth enabled but header absent | | INVALID_API_KEY | Wrong API key provided |

Concurrency Model

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

Configuration

Set via environment variables or .env file (prefix: MCP_BRIDGEKIT_):

| Variable | Default | Description | |----------|---------|-------------| | REDIS_URL | redis://localhost:6379 | Redis connection | | MAX_SESSIONS | 100 | Max concurrent MCP sessions | | SESSION_TTL_SECONDS | 3600 | Session expiry (1 hour) | | TIMEOUT_THRESHOLD_SECONDS | 25.0 | Seconds before queuing as background job | | JOB_RESULT_TTL_SECONDS | 600 | How long job results stay in Redis | | DEFAULT_MCP_COMMAND | python | Default MCP server command | | DEFAULT_MCP_ARGS | ["examples/mcp_server.py"] | Default MCP server args | | API_KEY | (empty) | v0.8 API key for X-API-Key header auth. Leave empty to disable. | | RATE_LIMIT_PER_MINUTE | 60 | v0.8 Max requests per user_id per minute. 0 = disabled. | | MAX_TOOL_RETRIES | 2 | v0.8 Retry transient tool failures N times with exponential backoff. | | WEBHOOK_URL | (empty) | v0.9 URL to POST job completion payload to. Leave empty to disable. | | ENABLE_SSE | true | v0.9 Publish completion events to GET /mcp/events/{job_id}. |

Security (Auth & Rate Limiting)

Added in v0.8.0. All features are opt-in — defaults are backward-compatible.

API Key Authentication

Protects /chat, /tools/, /job/, and /session/ endpoints. /health, /metrics, and /dashboard stay public for monitoring tools.

# Enable by setting a key
export MCP_BRIDGEKIT_API_KEY=your-secret-key

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

Rate Limiting

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

Retry with Backoff

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.

Push Notifications (Webhook & SSE)

Added in v0.9.0. Instead of polling GET /job/{job_id}, get instant push when a background job finishes.

Option 1: Webhook (AWS API / backend)

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.

Option 2: SSE (browser / real-time frontend)

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.

Using Both Together (AWS example)

# 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

Connecting to Any MCP Server

BridgeKit works with any MCP server — you just pass different mcp_config values. The mcp_config tells BridgeKit which command to spawn:

Supported MCP Servers

| MCP Server | command | args | Example Tools | |---|---|---|---| | AWS MCP | npx | ["-y", "@aws/aws-mcp"] | describe_instances, list_s3_buckets | | AWS CDK | npx | ["-y", "@aws/aws-cdk-mcp-server"] | GenerateCDK, ExplainCDK | | AWS Docs | npx | ["-y", "@aws/aws-documentation-mcp-server"] | search_documentation | | GitHub | npx | ["-y", "@modelcontextprotocol/server-github"] | search_repositories, create_issue | | Filesystem | npx | ["-y", "@modelcontextprotocol/server-filesystem", "/data"] | read_file, write_file | | PostgreSQL | npx | ["-y", "@modelcontextprotocol/server-postgres"] | query | | Custom Python | python | ["/path/to/server.py"] | Whatever you define |

Quick Example: AWS MCP from Your API

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.

Embedding in Your App

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)

Project Structure

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

TypeScript Version

A TypeScript implementation is available in ts/. Same architecture — session pooling, timeout handling, Redis queueing.

cd ts && npm install && npm run build && npm start

End-to-End Testing Guide

Verify everything works with these steps:

1. Start Services

# 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

2. Check Dashboard

Open http://localhost:8000/dashboard — should show 0 sessions, 0 jobs.

3. Call a Tool (instant response)

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.

4. Test Timeout Survival (background job)

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

5. Poll Job Result

curl http://localhost:8000/job/{job_id_from_step_4}

→ Returns {"status": "completed", "result": {...}} once the worker finishes.

6. List Available Tools

curl "http://localhost:8000/tools/test-001"

7. Cleanup Session

curl -X DELETE http://localhost:8000/session/test-001

8. Health Check

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.

Horizontal Scaling

BridgeKit is designed to scale horizontally:

| Component | How to Scale | Notes | |-----------|-------------|-------| | Web server | gunicorn --workers N | Dockerfile defaults to 4 workers. Each worker has its own event loop. | | RQ workers | Run multiple mcp-bridgekit-worker processes | docker-compose defaults to 3 replicas. All point to the same Redis. | | Redis | Use managed Redis (Upstash, ElastiCache, Redis Cloud) | Single Redis handles thousands of connections. | | Multi-machine | Run workers on different machines pointing to same Redis | MCP_BRIDGEKIT_REDIS_URL=redis://your-redis-host:6379 |

# 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

📐 Full Architecture Docs

See ARCHITECTURE.md for detailed diagrams and component docs. When running the server, visit /architecture for an interactive HTML version.

License

MIT