ramen

<p align="center"><img src="docs/img/logo.png" width="380" alt="Project Ramen"></p>

<p align="center">Multizone, highly available, enterprise-grade <b>MCP server</b> for GCP and AWS Kubernetes.<br>
Rust MCP node + Python 3.14 runtime workers, Streamable HTTP at the edge and gRPC inside, managed from a FastAPI console.</p>

<p align="center">
<a href="https://github.com/bkraad47/ramen/releases"><img height="20" src="https://img.shields.io/github/v/release/bkraad47/ramen?color=F26B3A&label=release&style=flat" alt="release"></a>
<a href="https://github.com/bkraad47/ramen/actions/workflows/ci.yml"><img height="20" src="https://img.shields.io/github/actions/workflow/status/bkraad47/ramen/ci.yml?branch=main&label=ci&style=flat" alt="ci"></a>
<a href="https://bkraad47.github.io/ramen/"><img height="20" src="https://img.shields.io/github/actions/workflow/status/bkraad47/ramen/pages.yml?branch=main&label=docs&style=flat" alt="docs"></a>
<a href="LICENSE"><img height="20" src="https://img.shields.io/badge/license-BSD--3--Clause-F26B3A?style=flat" alt="license"></a>
<a href="https://modelcontextprotocol.io"><img height="20" src="https://img.shields.io/badge/MCP-Streamable%20HTTP%20%2B%20gRPC-2B2622?style=flat" alt="MCP"></a>
</p>

**Docs: https://bkraad47.github.io/ramen/** · [Get started](https://bkraad47.github.io/ramen/get-started/) · [The MCP repo](https://bkraad47.github.io/ramen/wiki/mcp-repo/) · [Connect a client with OAuth](https://bkraad47.github.io/ramen/wiki/connect-oauth/) · [How it works](https://bkraad47.github.io/ramen/how-it-works/) · [Deploy on GCP](https://bkraad47.github.io/ramen/wiki/deploy-gcp/) · [Deploy on AWS](https://bkraad47.github.io/ramen/wiki/deploy-aws/) · [Contracts](docs/CONTRACTS.md) · [Releases](https://github.com/bkraad47/ramen/releases)

> **Streamable HTTP is the front door.** Every worker serves `POST /mcp` — a URL and a bearer header, nothing to
> install — next to the gRPC service it has had since 0.3.1, on the same port, through the same guards. Phones,
> browsers and hosted agent platforms connect directly; the stdio bridge stays for clients that only speak stdio.
> Per-user access through OAuth (the console is the authorization server), live-verified on GKE since 0.5.1.

**What is true today, before the pitch.** Current release **0.6.23**. The local stack and CI prove both
transports on real node processes on Linux and Windows. One GKE cluster has proved the gRPC path end to end
(0.3.2, 0.4.0) and the HTTP path with OAuth through the same load balancer (0.5.1, with a publicly trusted
certificate since 0.5.5). The AWS path has been applied to a real account since 0.5.6, and the published bridge
was server-tested against it in 0.5.8. 0.6.1 itself was deployed on both, two zones each, on 2026-10-04/05:
canary deploys (the stable track waits for the canary), `POST /mcp` over HTTP/1.1 and HTTP/2 through the load
balancer, per-token throttling shared across zones through Redis, OAuth sign-in through the bridge, the base URI,
and zone teardown. Everything below is written so those lines stay findable.

Ramen turns a **git repo of tools, resources and prompts** into a fleet of MCP workers behind a cloud load balancer.
Each worker pairs a **Rust MCP node** (Streamable HTTP and gRPC, bearer auth, IP allow-lists, health, logs) 1:1 with a
**Python 3.14 runtime** that pip-installs and runs your code. One **console** manages groups (tenants), environments,
zones, secrets, canary deploys, rebalancing, IP rules, logs, audit and backups — in the browser or through an API key.

- **Git → bucket → worker.** Deploy syncs the repo to a bucket; workers load by content hash. No git creds on pods.
- **Canary by default.** Roll a canary, smoke-test `tools/list`, then roll stable. Failure leaves stable untouched.
- **Multi-zone from day one.** Group → Environment → Zone → Worker; the LB routes on `ramen-group` / `ramen-zone`
  metadata, so one client config works for every zone.
- **Enterprise controls.** A role per group (Group Admin, Viewer or MCP User) plus global super admins, `rmk_` MCP keys, `rmn_` API keys, IP rules (per
  zone at the node, one Cloud Armor policy per group at the edge), secrets that are never displayed, an audit
  line for every action.
- **Transport: Streamable HTTP at the edge, gRPC inside.** `POST /mcp` for any client that can make an HTTP
  request; `ramen.v1.Mcp/Call` for teams that want gRPC internally. One set of guards serves both — the same
  functions, spelled `401 / 403 / 429` on one and `UNAUTHENTICATED / PERMISSION_DENIED / RESOURCE_EXHAUSTED` on the
  other — so the two paths cannot drift.
- **Cheaper: one Deployment per zone, not one per tool.** A worker is one Rust node plus one Python runtime that loads *every* tool of
  the group. A team with thirty small tools runs them on **one Deployment per zone** (two pods with a canary),
  behind one load balancer. Container-per-MCP-server designs run thirty. Autoscaling adds pods for load, not for
  tool count.
- **Secure, in one sentence.** User code never runs in the process that holds the keys and does the auth: the Rust
  node checks every call and hands the message to a separate Python process it can kill and respawn.

## Built on how organizations work

Groups own tools in git, environments pin a ref and a set of zones, people hold a role per group, agents and
clients sign in as themselves, and every deploy is a canary, a smoke test and a rollout. Underneath it is gRPC,
JSON-RPC 2.0 and a Rust node; **you code in Python**. The longer argument is
[How it works and why](https://bkraad47.github.io/ramen/how-it-works/).

> **Start here** · the demo group repo **[ramen-demo-mcp-group](https://github.com/bkraad47/ramen-demo-mcp-group)**
> (point a group at it and press Deploy) · the stdio bridge **[ramen-mcp-bridge on PyPI](https://pypi.org/project/ramen-mcp-bridge/)**
> (`pip install ramen-mcp-bridge`; signs you in with `--oauth` or carries a group key) · HTTP clients such as
> Claude Code, Claude Desktop and Cursor need neither: they connect with a group key, and Claude Code can also
> [sign you in with OAuth](https://bkraad47.github.io/ramen/wiki/connect-oauth/).
> Every feature and where it is managed: [How it works](https://bkraad47.github.io/ramen/how-it-works/).

## Quickstart (local, 5 commands)

Needs Docker with compose v2, `uv`, `git` and `make`. The first run builds two images and takes three to five minutes.

```sh
git clone https://github.com/bkraad47/ramen && cd ramen
make up       # Firestore emulator + console https://localhost:8443 + one worker (localhost:8080: Streamable HTTP + gRPC)
make demo     # zone, group `demo` from the demo repo, an rmk_ key, a canary deploy, then a tools/call
#   PASS: demo_calculator_tool(2,3,add) -> 5      <- the success line
open https://localhost:8443    # self-signed cert; login admin@ramen.local / changeme-ramen
make down     # stop and remove volumes
```

`make demo` is safe to re-run: an existing zone, group or environment answers "exists" and a fresh key is
generated each time.
Then connect your own client with an **`rmk_` MCP key** (Groups → demo → *Generate key* → Deploy). It is a URL and
a header — put the key in `RAMEN_MCP_KEY` and drop this into any `mcpServers` config:

```json
{"mcpServers": {"ramen-demo": {"url": "http://localhost:8080/mcp",
  "headers": {"Authorization": "Bearer ${RAMEN_MCP_KEY}", "ramen-group": "demo", "ramen-zone": "local"}}}}
```

Anything that can make an HTTP request is a client:
```sh
curl -s http://localhost:8080/mcp -H "Authorization: Bearer $RAMEN_MCP_KEY" -H 'Content-Type: application/json' \
  -H 'ramen-group: demo' -H 'ramen-zone: local' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"demo_calculator_tool","arguments":{"var1":2,"var2":3,"func":"add"}}}'
# {"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"5"}],"isError":false}}
```

Clients that only speak stdio use the bridge, which forwards to the same worker over gRPC:
```sh
pip install ramen-mcp-bridge                # its own package (github.com/bkraad47/ramen-mcp-bridge); also in the worker image
RAMEN_MCP_KEY=<the key shown once> ramen-mcp-bridge --target localhost:8080 --insecure --group demo --zone local
```

> `rmk_` **MCP keys** go to workers (`Authorization: Bearer`, on HTTP or as gRPC metadata) and are generated on
> the **group page**. `rmn_` **API keys** go to the console (`X-Ramen-Api-Key`) for automation and are generated
> on the **API keys** page. They are not interchangeable. For a token scoped to one *person* rather than a shared
> key, register an OAuth client on the Config page: the worker's `401` tells an OAuth-capable client where to
> sign in. Full walkthrough with the `mcp` SDK and a raw `grpcurl` call:
> [Get started](https://bkraad47.github.io/ramen/get-started/)
> (also in [`deploy/local/README.md`](deploy/local/README.md)).

## Screenshots

| Login | Dashboard, load per zone and group |
|---|---|
| ![login](docs/img/login.png) | ![dashboard](docs/img/dashboard.png) |

| Group: environments, deploy jobs, zones/workers, MCP keys | Deploy job with streamed log |
|---|---|
| ![group](docs/img/group.png) | ![deploy job](docs/img/deploy-job.png) |

| Secrets (names only, values never shown) | Logs (one JSON line per MCP call, downloadable) |
|---|---|
| ![secrets](docs/img/secrets.png) | ![logs](docs/img/logs.png) |

## Transport, and what secures each hop

Workers speak **Streamable HTTP** (`POST /mcp`, one JSON-RPC 2.0 message per request, MCP spec 2025-06-18) **and
gRPC** (`ramen.v1.Mcp/Call`, one message as `bytes body`) on the same port ([contract §16](docs/CONTRACTS.md),
[§11](docs/CONTRACTS.md)). MCP itself is unchanged — your client and your tools see the standard messages. The two
transports share one implementation of every check: the HTTP handler turns the request headers into the same
metadata map and calls the same guard and dispatch functions the gRPC service calls, so a check added to one is on
both o