Skip to main content

ramen-mcp-bridge

A stdio MCP server that forwards every JSON-RPC message to a Ramen worker's ramen.v1.Mcp/Call over gRPC. It exists for MCP clients that can only start a local process (stdio) — Claude Desktop, Cursor, and the reference mcp SDK all speak Streamable HTTP directly against Ramen's edge and don't need it; see Get started for that path instead.

Install

pip install ramen-mcp-bridge        # → ramen-mcp-bridge on PATH
# or: uv tool install ramen-mcp-bridge

Use

Against a local worker (plaintext, no TLS):

RAMEN_MCP_KEY="$KEY" ramen-mcp-bridge --target localhost:8080 --insecure --group demo --zone local

Against a cloud deployment (GCP GKE or AWS EKS) fronted by a load balancer with a publicly-trusted certificate (the default since Ramen v0.5.5 — see deploy/README.md):

ramen-mcp-bridge --target <public-hostname>:443 --tls --key rmk_… --group demo --zone a

--tls alone verifies against your system's CA trust store — nothing to download, no kubectl command. An older cluster still using the self-signed fallback needs its CA pulled once (kubectl -n ramen-system get secret ramen-console-tls -o jsonpath='{.data.tls\.crt}' | base64 -d > ramen-lb.pem) and a --ca ramen-lb.pem flag.

Sign in as yourself (0.2.0)

Instead of a shared rmk_ group key, the bridge can sign you in through the console — with your password, a magic link, or the identity provider the console is configured with (Microsoft Entra ID, Google Workspace, any OIDC issuer). A super admin registers an OAuth client on the console's Config page with the redirect URI http://127.0.0.1/callback (any port) and gives you its client id; your account needs a role in the group (an MCP User is enough):

ramen-mcp-bridge --target <public-hostname>:443 --tls --oauth https://<public-hostname> --client-id <client id> \
  --group demo --zone a

The first run opens your browser on the console's sign-in page (--no-browser prints the URL instead). Access tokens are scoped to mcp:<group>:<zone>, refreshed before they expire and after the worker answers UNAUTHENTICATED; every call the worker logs then names your account (user:<id>), not a key.

Where the tokens live (0.3.0). In the bridge's memory, nowhere else, unless you ask: --keychain keeps them in the operating system's secret store (macOS Keychain through security, a Secret Service such as GNOME Keyring through secret-tool), behind its own access control; --token-file <path> keeps them in a plain file with mode 0600, meant for automation only. Thirty minutes after the last call the bridge forgets its tokens (--idle-timeout, seconds, 0 disables), and the next call needs a fresh sign-in. When a sign-in is needed while an MCP client is connected the bridge does not block: it starts the browser flow and answers the call with error -32001 whose message carries the sign-in link (data.sign_in_url too), so an AI client can show it to you; once you approve, the next call goes through. Environment: RAMEN_BRIDGE_OAUTH, RAMEN_BRIDGE_CLIENT_ID, RAMEN_BRIDGE_KEYCHAIN=1, RAMEN_BRIDGE_TOKEN_FILE, RAMEN_BRIDGE_IDLE_TIMEOUT.

Expiry mid-task is invisible and safe. When the access token runs out while a client is working, the worker answers UNAUTHENTICATED before the call reaches any tool code; the bridge refreshes the token and repeats that one call. A tool is never run twice by the bridge: a call that reached the runtime either returns a result or an error, and neither is retried. The browser only reappears when the bridge has forgotten its tokens (thirty minutes idle, or a new bridge process without --keychain/--token-file), when the refresh token itself has expired on the console (thirty days unused), or when it was revoked because your role, password or account changed. The MCP session the client holds is bound to your account, not to the token, so it survives the refresh.

Point an MCP client at it directly:

{"mcpServers": {"ramen-stdio": {"command": "ramen-mcp-bridge",
  "env": {"RAMEN_BRIDGE_TARGET": "<public-hostname>:443", "RAMEN_BRIDGE_TLS": "1",
          "RAMEN_MCP_KEY": "rmk_…", "RAMEN_BRIDGE_GROUP": "demo", "RAMEN_BRIDGE_ZONE": "a"}}}}

Every flag has a RAMEN_BRIDGE_* environment variable equivalent (--target → RAMEN_BRIDGE_TARGET, --tls → RAMEN_BRIDGE_TLS=1, --group → RAMEN_BRIDGE_GROUP, --zone → RAMEN_BRIDGE_ZONE) so the key never has to sit in a client's config file — RAMEN_MCP_KEY (or RAMEN_BRIDGE_KEY) is enough. --health [SERVICE] checks grpc.health.v1 and exits 0 when SERVING, for a liveness probe.

Develop

uv sync --group dev
uv run pytest
./gen_proto.sh   # regenerate src/ramen_proto from proto/ramen/v1/mcp.proto after a proto change

License: BSD-3-Clause, same as ramen.

Metadata

Release files for ramen-mcp-bridge 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ramen-mcp-bridge 0.3.0
File Size Uploaded Provenance Actions
ramen_mcp_bridge-0.3.0.tar.gz 117.5 kB With provenance Details for ramen_mcp_bridge-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ramen-mcp-bridge 0.3.0
File Interpreter ABI Platform Actions
ramen_mcp_bridge-0.3.0-py3-none-any.whl Python 3 none any Details for ramen_mcp_bridge-0.3.0-py3-none-any.whl

Total release size: 135.7 kB

Release files / ramen_mcp_bridge-0.3.0.tar.gz

Download URL ramen_mcp_bridge-0.3.0.tar.gz
Size 117.5 kB
Tags Source
SHA-256 checksum
How to use checksums
0de0b2c8f6eeaabc4c458f68bc9d240bc88c42abaa42b2cd750a1497466706cb
BLAKE2b-256 checksum
How to use checksums
06771a1d959e3b57321e91012602907aabe9f72f9190a857b8e4c59910d6eada
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.

Transparency log

Release files / ramen_mcp_bridge-0.3.0-py3-none-any.whl

Download URL ramen_mcp_bridge-0.3.0-py3-none-any.whl
Size 18.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3ae27301df16b5252462fc30205b71be6934a1c6d6f2eeb2bd1f744caad817c7
BLAKE2b-256 checksum
How to use checksums
6497d1193cfcae705c1dd5a4475ca23777bf274d4bf969af5e66a209c292414b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.

Transparency log

Security for ramen-mcp-bridge 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for ramen_mcp_bridge-0.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page