bridge

Bridge MCP Gateway acts as a centralized MCP-native proxy and security layer. It provides native MCP protocol support, session management, and OAuth2 OBO token exchange to securely connect clients to MCP servers. The gateway exposes a RESTful API that wraps the underlying MCP protocol, enabling clients to connect to MCP servers, list available tools, invoke tools, and read resources through authenticated sessions. Typical usage involves authenticating with Keycloak to obtain a user JWT, which the gateway then exchanges for a service-specific token, establishes an MCP session with the target server, and routes subsequent MCP calls through the gateway while handling authentication, authorization, and auditing.

Key capabilities include: secure session management with per-client isolation, MCP Initialize/Initialized handshake handling, streamable HTTP transport for MCP, OIDC authentication with Keycloak integration, automatic token exchange via OBO flow, and health checks with circuit-breaker protection. The gateway also supports integration testing and provides endpoints to manage sessions and tools, making it straightforward to programmatically interact with MCP servers without implementing the MCP protocol logic in each client.

To use, first start the gateway, then use the REST API to connect to an MCP server, enumerate tools, call a tool, and fetch resources. For dashboards and monitoring, you can access the development dashboard as described in the repository, and observe health metrics, request counts, and system status exposed by the gateway.

Prerequisites:

• Python 3.12 or newer
• uv package manager installed and available in PATH
• Access to an MCP server and Keycloak (or equivalent OIDC provider) for authentication

Installation steps:

1. Clone the repository:

git clone https://github.com/your-org/mcp-gateway.git
cd mcp-gateway

2. Install dependencies and set up uv (as described in the project):

uv sync

3. Copy and configure environment variables:

cp .env.example .env
# Edit .env with your configuration (e.g., keys for Keycloak, MCP server endpoints, DB if used)

4. Run the gateway (via uv):

uv run python -m mcp_gateway.main

The gateway will start on http://127.0.0.1:8000 by default.

Optional: To run tests or development tooling, follow the project’s guidance for uv test commands and code formatting if you plan to contribute.

Notes and tips:

• Environment variables control host, port, logging, and security policies; ensure HOST, PORT, and DEBUG are set appropriately in .env.
• Ensure your Keycloak (or OAuth2 provider) is reachable so the gateway can perform OBO token exchanges.
• The gateway exposes MCP-specific endpoints under /api/v1/mcp/... for connect, tools, resources, and calls; use these to integrate MCP capabilities into your clients.
• If you encounter connectivity issues, check circuit-breaker state and health check endpoints to diagnose per-server failures.
• The dashboard (when enabled) is under active development; refer to the README for its status and access instructions.
• For production deployments, consider configuring Redis-backed rate limiting and an observability stack (Prometheus/Grafana) as part of Phase 3 features.