You can perform basic arithmetic on two numbers through one MCP tool.
Add two numbers (func: "add")
Subtract two numbers (func: "subtract")
Multiply two numbers (func: "multiply")
Divide two numbers (func: "divide")
Requires var1 and var2 as numbers, and func as one of the four allowed operations
Rejects any extra input properties
Docs: https://bkraad47.github.io/ramen/ · Get started · The MCP repo · Connect a client with OAuth · How it works · Deploy on GCP · Deploy on AWS · Contracts · 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.
Build and deploy your own MCP tools across zones. Ramen turns a git repo of tools, resources and prompts into a fleet of MCP workers behind a cloud load balancer, and keeps who-can-call-what, secrets, canary gates and the audit trail in one console. It is a platform for your tools, not a gateway in front of someone else's. 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, gated. Roll a canary, smoke-test tools/list, diff its tool schemas against stable
(breaking changes stop unless you say breaking: true), run the repo's golden cases, 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.
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.
Start here · the demo group repo ramen-demo-mcp-group (point a group at it and press Deploy) · the stdio bridge ramen-mcp-bridge on PyPI (
pip install ramen-mcp-bridge; signs you in with--oauthor 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. Every feature and where it is managed: How it works.
Related MCP server: MCP Manager
Needs Docker with compose v2, uv, git and make. The first run builds two images and takes three to five minutes.
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 volumesmake 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:
{"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:
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:
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's401tells an OAuth-capable client where to sign in. Full walkthrough with themcpSDK and a rawgrpcurlcall: Get started (also indeploy/local/README.md).
Login | Dashboard, load per zone and group |
|
|
Group: environments, deploy jobs, zones/workers, MCP keys | Deploy job with streamed log |
|
|
Secrets (names only, values never shown) | Logs (one JSON line per MCP call, downloadable) |
|
|
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,
§11). 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 or on neither.
Why the node is Rust. A worker runs two processes with one job each. ramen-node (Rust + tonic) owns what must
not be slowed down or broken by user code: the gRPC surface, key checking, source-range checking, the blocked-name
filter, concurrency bounds, deadlines, health and the access log. It is a small static binary with no interpreter
and no user code in its address space. ramen_runtime (Python 3.14) owns what users write: pip install, validation,
secret substitution, the call. They talk over newline-delimited JSON-RPC on stdin/stdout (§2),
so there is no extra socket to secure, and the runtime is killed after an idle timeout — a crash or leak in tool
code costs one respawn, not the process holding the keys.
Hop | What protects it |
client → edge (HTTP) | TLS at the load balancer; the credential in |
client → bridge → edge (stdio) | a child process on the client's own machine, speaking gRPC to the edge; plaintext unless |
edge → node | TLS ends at the load balancer; h2c to the node unless the node has its own certificate; Cloud Armor (GCP) or WAF (AWS) IP rules, one policy per group |
every | constant-time key compare; source range against the right |
edge → node, without a key | only |
anything else → the pod | the worker |
node → runtime | stdio inside the pod; no network surface |
runtime → bucket | the zone's own cloud identity (GCP service account with Workload Identity, AWS IAM role with IRSA), scoped to the group's prefix and secrets |
console → node | cluster-internal, never through the load balancer; |
Five details behind that table matter in practice. The origin allowlist is empty by default, so every browser
Origin is refused until you add one. The source-range check reads the x-forwarded-for entry a proxy appended
(hop count 2 on GCP, 1 on AWS), and a wrong count denies rather than admits. The allowlist itself defaults to
everything until you set IP rules. An IP lock must include the console's own range, because a deploy smoke-tests
tools/list as an ordinary call. grpc.health.v1.Health is deliberately unauthenticated so load balancers can
probe it, and reports SERVING only once the runtime has loaded the group's code.
What is verified, in four lines.
Both transports through every guard, on real node processes, in CI on Linux and on a Windows runner that builds the node natively (0.5.0).
The GCP path live through the Gateway load balancer on a throwaway project every release, most recently 0.6.1 with two zones, OAuth, the Redis throttle and a real teardown.
The AWS path applied to a real account in 0.5.6, 0.5.8, 0.6.0 and 0.6.1, each emptied the same day; the published bridge server-tested against it in 0.5.8.
Covered by tests only, never on a real load balancer: node TLS, and the size and in-flight caps.
By design, a group's code runs in a process that holds that group's secrets. Isolation between groups is the pod, the namespace and the per-zone identity.
Full write-up: Transport and what secures each hop.
Target | Status | Guide |
GCP — GKE Autopilot, Firestore, GCS, Secret Manager, global HTTPS LB (GKE Gateway, header-routed gRPC and Streamable HTTP, gRPC health checks), Cloud Armor | verified on a throwaway project every release, most recently 0.6.1: two zones, OAuth, the Redis throttle shared across zones, real zone teardown | |
AWS — EKS, DynamoDB, S3, Secrets Manager, ALB (gRPC and HTTP/1.1 target groups), WAF (Terraform or CloudFormation) | applied to a real account since 0.5.6; bridge server-tested in 0.5.8 | |
Local — docker compose | CI e2e on every push |
Bring-up on GCP is terraform apply → make push → helm upgrade --install → add a zone and a group in the
console → Deploy. About 25 minutes, mostly waiting for GKE and the load balancer. The load balancer gets a
publicly-trusted certificate automatically (a free sslip.io hostname derived from the static IP — no domain to
buy, since 0.5.5). Clients then use https://<public_hostname>/mcp with Authorization: Bearer rmk_ and the
ramen-group / ramen-zone headers (the same address serves the console and, by those headers, every zone);
stdio-only clients point the bridge at <public_hostname>:443 --tls — no --ca, nothing to import.
Full guide with the demo repo, env.yaml and local development: The MCP repo, structure and local development.
A group repo is any git repo with mcp/tools/<name>/<name>.py + <name>.json (and resources/, prompts/,
requirements.txt). Start from ramen-demo-mcp-group; the
contract is in the MCP repo page. Secrets are referenced as
{{$group.NAME}} and substituted by the runtime at call time. Nothing about the transport leaks into tool code.
Declare output and the worker publishes it as outputSchema and validates every result; add mcp/tests.yaml and
your cases gate every deploy (0.7.0).
Dir | What |
FastAPI + Jinja2 + HTMX manager UI and | |
Rust MCP server node (tonic: | |
Python 3.14 runtime (loads protos, pip installs, runs calls, resolves secrets) | |
| |
compose, Helm charts, Terraform (GCP, AWS), CloudFormation | |
Cloud-ops agent skills: deploy-gcp, deploy-aws, rotate-keys, backup-restore, scale-zone | |
Black-box conformance (gRPC + bridge), e2e and cloud suites | |
This site's sources; |
Architecture: ARCHITECTURE.md · Changes: CHANGELOG.md · Versions: tracker
make test # runtime-py and console (pytest, 90% coverage gate) plus node-rs (fmt, clippy, test)
make test-harness # tests/: conformance + e2e (skips without a running stack)
make proto # regenerate Python stubs from proto/ (Rust stubs build via tonic-build)
make demo-worker # node + runtime locally without Docker
uv run --project docs --group docs mkdocs serve # docs at http://127.0.0.1:8000See CONTRIBUTING.md — use it, fork it, change it, with attribution; renaming it as a new commercial product of your own is not acceptable. Related repositories and which versions go together: Releases.
BSD-3-Clause © 2026 Raad. See LICENSE.
Add, subtract, multiply or divide two numbers and return the result as a number. Pure and stateless: no side effects, no network, no auth beyond the group's key, no rate limit of its own. Division by zero returns a tool error (isError) with a one-sentence message instead of a value. Use it when an exact arithmetic result matters; for anything beyond one binary operation, chain calls or compute in the model.
| Name | Required | Description | Default |
|---|---|---|---|
| func | Yes | operation to apply as var1 <func> var2 | |
| var1 | Yes | first operand (left-hand side); any finite number | |
| var2 | Yes | second operand (right-hand side); must be non-zero for divide |
| Name | Required | Description |
|---|---|---|
| result | Yes | var1 <func> var2 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so: pure/stateless, no side effects, no network, auth only via the group key, no own rate limit, and the division-by-zero path returns isError with a one-sentence message rather than a value. That is exactly the behavioral context an agent needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, front-loaded with purpose, then behavior, then the error case, then routing guidance. Every sentence earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists so return values need no explanation, and the description still covers the one non-obvious edge case (division by zero producing a tool error). Nothing needed to call this tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents func's enum and both operands (including the non-zero constraint for divide). The description adds only the 'two numbers' framing and the left/right ordering implied by var1 <func> var2, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb set (add, subtract, multiply, divide) plus the resource (two numbers) and the return type. It is trivially distinguishable from the arithmetic-free siblings unit_convert and word_count.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names when to use it ('when an exact arithmetic result matters') and when not to ('for anything beyond one binary operation, chain calls or compute in the model'). The alternative path is stated, not implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert a value between units of length (mm, cm, m, km, inch, foot, yard, mile), mass (mg, g, kg, tonne, ounce, pound) or temperature (celsius, fahrenheit, kelvin) and return the converted number. Pure and stateless, no side effects, no auth beyond the group's key. Units are matched case-insensitively by the names listed; an unknown unit or a conversion across families (length to mass) returns a tool error (isError) naming the accepted units. Use it for exact factor-based conversions; it does not handle currencies, dates or compound units such as km/h.
| Name | Required | Description | Default |
|---|---|---|---|
| value | Yes | the quantity to convert, in from_unit | |
| to_unit | Yes | unit of the result, same family as from_unit | |
| from_unit | Yes | unit of value, e.g. km, pound, celsius |
| Name | Required | Description |
|---|---|---|
| result | Yes | value expressed in to_unit |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so: pure/stateless, no side effects, no auth beyond the group key, case-insensitive unit matching, and explicit error semantics (tool error with isError naming accepted units on unknown unit or cross-family conversion). That is unusually complete behavioral disclosure for a stateless utility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads purpose and return value in the first sentence, then behavior, then routing guidance. Every clause carries distinct information (units, families, case rules, error behavior, exclusions) with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return formatting need not be elaborated, yet the description still states the result is a converted number. Combined with the auth, statelessness and error details, an agent has everything needed to call this correctly with three required parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3; the description still adds real value by listing the accepted unit names, stating that matching is case-insensitive, and defining the cross-family failure mode for from_unit/to_unit. It stops short of documenting numeric ranges or precision/rounding behavior for value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb (convert) and resource (units of length, mass, temperature) and enumerates the exact accepted unit symbols, so an agent knows precisely what domain this covers. It also carves itself apart from a generic calculator sibling by excluding currencies, dates and compound units like km/h.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Use it for exact factor-based conversions; it does not handle currencies, dates or compound units such as km/h" gives an explicit when-to-use plus a concrete when-not-to-use set. Although it does not name the sibling tools, the exclusions are the operationally relevant routing signal and leave nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Count the characters, words and lines of a text and return the three counts as an object. Pure and stateless: the text is not stored or sent anywhere; no auth beyond the group's key. Words are whitespace-separated runs; lines are newline-separated (a trailing newline does not add a line); characters are Unicode code points including whitespace. Use it when a model needs an exact count rather than an estimate; it does not tokenise or detect language.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | the text to count; may be empty, which yields zeros |
| Name | Required | Description |
|---|---|---|
| lines | Yes | newline-separated lines; 0 for an empty text |
| words | Yes | whitespace-separated runs |
| characters | Yes | Unicode code points, whitespace included |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden, and it delivers: 'Pure and stateless: the text is not stored or sent anywhere; no auth beyond the group's key.' It also pins down exact counting semantics (whitespace-separated words, newline-separated lines without a trailing-newline artifact, Unicode code points including whitespace), which is unusually complete for a no-annotation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, front-loaded with what it counts and what it returns, then safety, then precise definitions. Every sentence contributes something an agent cannot get from the schema, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value documentation is unnecessary, yet the description still names the object shape. For a stateless one-parameter utility it covers purpose, selection, safety/auth, and edge-case semantics, leaving nothing an agent needs before calling it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single parameter is already documented, including the empty-string case. The description's word/line/character rules govern how the result is computed rather than adding new meaning to the `text` parameter, so the baseline of 3 for high schema coverage is the right level.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a precise verb and resource ('Count the characters, words and lines of a text') plus the exact return shape ('return the three counts as an object'). It is trivially distinguishable from the unrelated siblings demo_calculator_tool and unit_convert, and no other tool in the set could be confused with it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly gives the selection condition ('Use it when a model needs an exact count rather than an estimate') and the when-not cases ('it does not tokenise or detect language'). An agent knows both when to reach for this tool and which related tasks it must not use it for, without any inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.7.1demo_calculator_tool4 fields changedInput schema / properties / func / descriptionPrevious value: -"operation"New value: +"operation to apply as var1 <func> var2"Input schema / properties / var1 / descriptionPrevious value: -"first operand"New value: +"first operand (left-hand side); any finite number"Input schema / properties / var2 / descriptionPrevious value: -"second operand"New value: +"second operand (right-hand side); must be non-zero for divide"Output schema / (root)Previous value: -nullNew value: +{
+ "properties": {
+ "result": {
+ "description": "var1 <func> var2",
+ "type": "number"
+ }
+ },
+ "required": [
+ "result"
+ ],
+ "type": "object"
+}unit_convertword_countv0.1.0demo_calculator_toolScored across 3 tools
Each tool targets a completely different operation: arithmetic (demo_calculator_tool), unit conversion (unit_convert), and text counting (word_count). There is no overlap or plausible misselection between them, and each description clearly states its scope and limits.
All names are snake_case and readable, and two follow a clean noun_verb pattern (unit_convert, word_count). The outlier demo_calculator_tool adds an unnecessary 'demo_' prefix and '_tool' suffix, a minor deviation from the otherwise consistent convention.
Three tools is on the thin side for a general-purpose utility server, but each is distinct and clearly earns its place with no filler. It is reasonable if the server is intentionally a small demo/utility set.
Each individual tool is self-contained and complete for its narrow function, but the server has no coherent domain, so there is no lifecycle or CRUD surface to evaluate. As a set it reads as a few unrelated utilities rather than a complete toolkit.
Self-hosted federated MCP gateway: one OAuth 2.1 MCP server in front of N apps, user-level scopes.
Hosted MCP server with managed OAuth for 15+ toolkits: Google Workspace, Fitbit, Oura, Kalshi, etc.
Hosted MCP server for GA4, Google Ads and Search Console. Google OAuth, nothing to install.
Self-hosted MCP server: 26 deterministic dev, security, and EVM tools.
