Enterprise MCP Bridge Documentation

The Production-Grade Wrapper for MCP

A robust FastAPI-based wrapper that exposes any Model Context Protocol (MCP) server over plain HTTP/JSON. This project is engineered for enterprise production use, focusing on security, scalability, and ease of integration.

Get Started

Screenshot of the Enterprise MCP Bridge example deployment with application, jaeger, grafana and keycloak

Why this project?

Most existing MCP examples are designed for local development or simple demos and fall short for real-world applications. They are typically:

Single-user CLI processes: Driven by a local client.
Ephemeral: State is lost as soon as the process ends.
Lacking multi-tenancy: No built-in orchestration for concurrent users or sessions.
Hard to control: Lack of integration into enterprise monitoring tools.
No simple integration: For MCP components into REST-based microservice architectures.
Missing a consistent security model: For handling delegated permissions (e.g., OAuth) for downstream resources.

This project directly addresses these gaps. It's designed for enterprise production use, with a focus on security, scalability, and ease of integration. For small private deployments, it's probably not the right fit.

Robust Session & User Management

Multi-User & Multi-Session: Securely manage multiple isolated user contexts and concurrent sessions.
Stateful & Stateless Modes: Supports both stateless "fire-and-forget" calls and stateful sessions.
Lifecycle & Resource Hygiene: Explicit endpoints for session management and automatic cleanup of idle sessions.
Pluggable for Scalability: Session manager is swappable for distributed backends like Redis.

Integrated Security & Authentication

Centralized hosting of the MCP server: The server can be hosted in a centralized manner, allowing multiple clients to connect and interact with it concurrently, while your IT manages the underlying infrastructure, permissions and monitors it.
Built-in OAuth2: Natively handles OAuth2 token exchange with brokers like Keycloak.
Automatic Token Injection: Securely injects tokens into tool calls, simplifying client logic.
Automated Token Refresh: Manages token refresh transparently for long-lived, secure sessions.

Developer Experience & API Design

REST-first Interface: All tool discovery and invocation happen over standard HTTP/JSON.
Automatic Tool Endpoints: Each MCP tool is automatically mapped to a canonical REST endpoint.
Structured Error Handling: Maps MCP errors to standard HTTP status codes.
Auto-Generated API Docs: Built on FastAPI, providing interactive OpenAPI (Swagger) and ReDoc documentation.
Containerized Deployment: Designed for Docker and Kubernetes with structured logging and monitoring.

Quick Start

Run the local demo with a default MCP server.

git clone https://github.com/inxm-ai/enterprise-mcp-bridge.git
cd enterprise-mcp-bridge
pip install "app[all]"
uvicorn app.server:app --reload

Open the API docs: http://localhost:8000/docs

You can test it with the following command:

curl -X 'POST' \
'http://127.0.0.1:8000/tools/add' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"a": 2,
"b": 1
}'

This will return a JSON response with the result of the addition.

For more advanced usage, including session management and authentication, see the Examples.

Session vs. Stateless Calls

Mode	How	When to use
Stateless	`POST /tools/{tool}` (no session header)	Simple one-off tool execution
Stateful	`POST /session/start` then include header/cookie	Conversations, multi-step pipelines

Session Management CLI Examples

Start a Session:

curl -X POST http://localhost:8000/session/start -c cookies.txt

Use the Session:

curl -b cookies.txt -X POST http://localhost:8000/tools/add -H 'Content-Type: application/json' -d '{"a":2,"b":3}'

Close the Session:

curl -b cookies.txt -X POST http://localhost:8000/session/close

Examples

Explore ready-to-run examples. Switch tabs to see setup and details for each.

Full-Stack Docker Compose Deployment

This is the example from example/token-exchange-m365. It brings up authentication (Keycloak + OAuth2-Proxy), the Enterprise MCP Bridge, and observability (Jaeger, Prometheus, Grafana).

All the things you need in an Enterprise

Federated SSO via Keycloak with token exchange to Microsoft Entra; OAuth2-Proxy protects the app edge.
Least-privilege token handling: user tokens never reach the browser tools; the server exchanges and injects provider tokens per request.
Operational visibility: OTLP traces to Jaeger; metrics for Prometheus; default Grafana Dashboard and connection set up.
Safety rails: route scoping with MCP_BASE_PATH, tool allow/deny lists, and containerized runtime.
Enterprise identity mapping: realms and provider aliases for multi-tenant setups.

This is not a fully production-ready example, but a starting point for your own deployment. It is designed to be easily extensible and customizable to fit your specific needs.

Prerequisites

Docker & Docker Compose
Azure CLI (az)
A free Microsoft Entra (Azure AD) developer account
An OpenAI-compatible API key (for the MCP server)

Start the full stack

From the example folder, start everything with one script:

cd example/token-exchange-m365
./start.sh

Then open https://inxm.local. You’ll be redirected to Keycloak at https://auth.inxm.local to log in. On first run, the script also automates the Entra app registration.

Stop and clean up

./stop.sh

Stops the containers and removes local resources created by the demo.

Service configuration (app-mcp-rest)

Key settings for the Enterprise MCP Bridge container:

services:
    app-mcp-rest:
        container_name: app.mcp-m365-rest-server
        image: ghcr.io/inxm-ai/enterprise-mcp-bridge:latest
        environment:
            # A human-readable name for the service, useful for logging and observability.
            SERVICE_NAME: mcp-m365-rest-server
            # The command to launch the specific MCP server that this REST wrapper will connect to.
            MCP_SERVER_COMMAND: npx -y @softeria/ms-365-mcp-server --org-mode
            # The name of the environment variable that the MCP server will use to receive the OAuth token.
            OAUTH_ENV: MS365_MCP_OAUTH_TOKEN
            # Specifies the authentication provider to use for token exchange.
            AUTH_PROVIDER: keycloak
            # Allows the REST server to trust self-signed certificates from the auth provider, useful for local development.
            AUTH_ALLOW_UNSAFE_CERT: true
            # The base URL of the Keycloak instance.
            AUTH_BASE_URL: https://auth.inxm.local
            # The Keycloak realm where the authentication is configured.
            KEYCLOAK_REALM: inxm
            # The alias for the external identity provider (in this case, Microsoft 365) within Keycloak.
            KEYCLOAK_PROVIDER_ALIAS: ms365
            # Sets a URL prefix for all the REST endpoints to prevent conflicts with other services.
            MCP_BASE_PATH: /api/mcp/m365
            # A comma-separated list of tool names to exclude from the REST endpoints.
            EXCLUDE_TOOLS: login,logout,verify-login
            # A comma-separated list of tool name patterns to include.
            INCLUDE_TOOLS: "*mail*"
            # The endpoint for OpenTelemetry Protocol (OTLP) to send trace data to Jaeger for monitoring.
            OTLP_ENDPOINT: http://jaeger:4317
        depends_on:
            keycloak:
                condition: service_healthy
            jaeger:
                condition: service_started
        ports:
            - "8000:8000"
        labels:
            - "oauth2-proxy.enable=true"
        networks:
            - private

OAuth Token Integration

The server can retrieve, refresh, and inject OAuth tokens for downstream services, simplifying security for your tools.

Flow Diagram: Login

sequenceDiagram
    participant User
    participant AppIngress as App-Ingress (NGINX)
    participant OAuth2Proxy as OAuth2-Proxy
    participant Keycloak as Keycloak (auth.inxm.local)
    participant AppFrontend as App-Frontend (UI)
    
    User ->> AppIngress: Access https://inxm.local
    AppIngress ->> OAuth2Proxy: Route Request
    OAuth2Proxy ->> Keycloak: Authenticate (redirect)
    Keycloak -->> User: Redirect for Login
    User ->> Keycloak: Log in
    Keycloak -->> OAuth2Proxy: Redirect with Code/Token
    OAuth2Proxy ->> AppIngress: Set Cookie/Header
    AppIngress ->> AppFrontend: Serve Frontend

Flow Diagram: Tool Request with Token Exchange

sequenceDiagram
    participant AppFrontend as App-Frontend
    participant AppIngress as App-Ingress (NGINX)
    participant OAuth2Proxy as OAuth2-Proxy
    participant AppMCPRest as App-MCP-Rest
    participant Keycloak as Keycloak
    participant DownstreamAPI as Downstream-API
    
    AppFrontend ->> AppIngress: Request Tool Execution
    AppIngress ->> OAuth2Proxy: Route Request
    OAuth2Proxy ->> AppMCPRest: Forward with Auth Token
    AppMCPRest ->> Keycloak: Request Downstream Token (Token Exchange)
    Keycloak -->> AppMCPRest: Return Downstream Token
    AppMCPRest ->> DownstreamAPI: Access API with Downstream Token

Minimal Example

This is the example from example/minimal-example. It uses the default MCP server and calls the add tool with a simple payload as a simple curl request.

cd example/minimal-example
./start.sh

Expected output includes a result of 3 indicating the add tool is working:

Default mcp example
Starting docker container
Calling the add tool with {"a": 2, "b": 1}
{"isError":false,"content":[{"text":"3","structuredContent":null}],"structuredContent":{"result":3}}

Memory Group Access

This is the example from example/memory-group-access. It demonstrates how to limit access to the memory of the Memory MCP Server (and thus the memory available to the LLMs) using your IAM Groups.

cd example/memory-group-access
./start.sh

Then open https://inxm.local and log in using one of the pre-configured users:

Username	Password	Groups	Access
`admin`	`admin123`	administrators	All group memories + personal
`john.engineer`	`engineer123`	engineering	Engineering memories + personal
`jane.marketing`	`marketing123`	marketing	Marketing memories + personal
`bob.sales`	`sales123`	sales	Sales memories + personal

Use the small forms that give you access to the @modelcontextprotocol/server-memory tools and try to access data you're not supposed to.

Contributing to Enterprise MCP Bridge

Thanks for your interest in contributing! This document explains how to propose changes, report issues, add features, improve docs, and release updates.

📌 Quick Start (TL;DR)

Fork & clone.
Create a branch: git switch -c feat/my-feature.
Create a virtual env (Python 3.10+).
Install locally (incl. dev deps): pip install -e ./app[dev].
Run tests: pytest -q.
Make changes + add/adjust tests.
Run lint & format.
Commit using a sensible message.
Open a Pull Request (PR).
Agree to the CLA if you haven't

🗂 Project Layout

app/
  server.py          # FastAPI app wiring
  routes.py          # REST endpoints & request/session orchestration
  models.py          # Pydantic-style data models
  session/           # Session abstraction & lifecycle mgmt
  session_manager/   # Session registry
  oauth/             # Token exchange + decorators
  mcp_server/        # Server parameter helpers
  test_*.py          # Tests (pytest)

🧪 Testing

We use pytest. Write tests for every new feature or bug fix. Favor small, explicit tests.

Run the full suite: pytest -q

🧹 Code Style & Quality

Follow standard Python style (PEP 8). Keep functions small, log appropriately, and avoid broad exception catches. Use type hints for new or changed public functions.

🔐 Security & Privacy

Never log raw OAuth tokens or secrets. Validate and sanitize user-provided values. Report vulnerabilities privately before opening a public issue.

🐞 Reporting Issues

Include your environment, install method, reproduction steps, expected vs. actual behavior, and logs (with sensitive data trimmed).

📝 Commit Messages & Pull Requests

Use Conventional Commits (e.g., feat: add session timeout config, fix: handle unknown tool error). Ensure your PR checklist is complete before submitting, including passing tests, updated documentation, and a clear commit history.

🤖 AI-Assisted Contributions

You may use AI tools, but you are the author of record. Carefully review all generated code, ensure it's well-tested, and avoid pasting secrets. Avoid blind bulk rewrites and instead use AI to draft boilerplate or explore alternative designs. Maintainers may request clarification on AI involvement if needed.

🧭 Roadmap Ideas

Feel free to open PRs for these ideas:

Add session timeout / eviction policy
Optional Redis / external session backend
Structured logging config & correlation IDs

Find more ideas in our GitHub issues.