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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.