The MCP repo: structure and local development
A group's tools live in a plain git repo. You write Python and one JSON file per package. No server code, no MCP SDK. The demo repo is the smallest complete example and the one every guide deploys.
The layout
mcp/
requirements.txt pip requirements the worker installs on load
env.yaml environment for your code, rendered from the group's secrets
tests.yaml golden tools/call cases, run on the canary before stable takes the code (0.7.0)
guardrails.yaml which tools get a pre/post check and with which engine (0.7.5)
guardrails/ the NeMo rails config (config.yml, *.co, actions.py) or your policy.py
tools/<name>/<name>.py the callable
tools/<name>/<name>.json the contract: type, name, description, callable, input, output, error
tools/<name>/utils/ optional helpers; this folder is on sys.path, so `import calculator_utils` works
resources/<name>/<name>.py+.json the same shape, plus uri and mime_type
prompts/<name>/<name>.json plus SKILL.md and settings.json, or a <name>.py callable (1.0)
apps/<name>/index.html an MCP App a tool can render its result in, plus app.yaml (1.0.0c)
skills/<name>/SKILL.md a skill an agent can install over MCP, with any files beside it (1.0.0c)
evals/promptfooconfig.yaml a promptfoo suite run against the canary on deploy (1.0.0c, see Evals)
llm-config/manifest.yaml client config fragments every person accepts at sign-in (1.0.0c, see LLM configs)
Three rules carry everything. The folder name, the name in the JSON and the Python file's stem must match.
type must match the parent folder. input maps each parameter to a JSON schema, and every parameter is required
unless its schema says otherwise. A package that breaks a rule is listed under errors in the deploy job and the
others still load.
A tool
{
"type": "tool",
"name": "demo_calculator_tool",
"description": "Add, subtract, multiply or divide two numbers.",
"callable": "calculator_func",
"input": {
"var1": {"type": "number", "description": "first operand"},
"var2": {"type": "number", "description": "second operand"},
"func": {"enum": ["add", "subtract", "multiply", "divide"], "description": "operation"}
},
"output": {"type": "number"},
"error": {"type": "string"}
}
def calculator_func(var1: float, var2: float, func: str) -> float:
ops = {"add": var1 + var2, "subtract": var1 - var2, "multiply": var1 * var2, "divide": var1 / var2}
if func not in ops:
raise ValueError(f"unknown func {func!r}")
return ops[func]
input becomes the MCP inputSchema. A return value that is not a string is JSON-encoded into the result text.
An exception becomes isError: true with ExceptionType: message and no traceback, so raise ValueError with a
sentence a model can act on.
Since 1.0.0c a worker runs up to RAMEN_RUNTIME_CONCURRENCY calls at once (default 4) on threads of one Python
process, so a slow tool or an LLM rail no longer holds every other call on the worker. Write tool code as if it ran on
several threads: keep state in the call (arguments, locals, input_responses()), not in module globals you mutate;
guard a shared client or cache with a lock; and expect two calls to be inside the same function at the same time.
A tool that must run alone can take a module-level threading.Lock() itself. Reloads wait for the calls in flight.
output is a JSON Schema and becomes the MCP outputSchema; the worker validates every result against it.
A scalar schema such as {"type": "number"} is published as an object with one result property and the value
comes back as structuredContent: {"result": 5} next to the text; an object schema is used as declared and the
returned dict is the structuredContent. A result that does not match is a tool error, invalid output: <path>:
<message>, so a tool cannot quietly change shape under a client. Tools without output behave as before.
Write the description for a model, not a human: what the tool returns, what fails and how (division by zero, an unknown unit), whether it has side effects, and when to use it or not. Scorers such as Glama's Tool Definition Quality Score read exactly that, and so does the agent choosing between tools.
Golden cases
mcp/tests.yaml turns your tests into a deploy gate. The console runs every case against the canary with
the group's first MCP key before the stable workers take the new code; one failing case aborts the deploy and the
job log names it and the difference.
cases:
- name: add
tool: demo_calculator_tool
args: {var1: 40, var2: 2, func: add}
expect: {text_contains: "42"}
- name: word count
tool: word_count
args: {text: "ramen is a bowl of noodles"}
expect: {subset: {structuredContent: {words: 6}}}
expect is one of text_contains (a substring of the result text), subset (part of the tools/call result,
matched field by field) or exact (the whole result). args may reference the group's secrets as
{{$group.VAR}}; the console resolves them before the call. A JSON-RPC error counts as a failure. A group without
an MCP key skips the cases with a warning; a malformed file fails the deploy before any zone changes.
A tool that asks for input (1.0, multi round-trip requests) gets two more forms, both from the demo repo:
- name: confirm_delete_note asks before it deletes
tool: confirm_delete_note
args: {note: todo}
expect: {input_required: [confirm]}
- name: confirm_delete_note deletes when the user confirms
tool: confirm_delete_note
args: {note: todo}
respond: {confirm: {action: accept, content: {confirm: true}}}
expect: {text_contains: 'Deleted the note "todo"'}
expect: {input_required: [<keys>]} passes when the tool's first answer asks for exactly those keys. respond:
{<key>: <answer>} makes the case a two-step call: when the tool asks, the console calls again with these answers
(and the requestState, if there was one), and expect applies to the final result. The console makes such a case
as a 2026-07-28 client that declares elicitation (form and URL), sampling and roots. It retries once: a tool that
asks again after the answers fails the case, and so does a tool that asks when the case has no respond. Every
other case is sent exactly as before.
Guardrails
mcp/guardrails.yaml opts tools into a check before the call and after the result, run in the runtime next to the
tool: NeMo Guardrails rails or a policy.py of your own, fail-closed by default. Golden cases run through them.
The whole story, with the demo repo's deterministic rails, is on Guardrails.
Resources and prompts
A resource is a tool with a uri and a mime_type whose callable returns the content. The demo's
demo_readme returns the group's README as text/markdown.
A prompt needs no code. Its JSON names a skill and a settings file instead of a callable, each
input parameter becomes a prompt argument, and {{param}} in the skill is substituted when a client asks for
it. The settings file is appended as a ## Settings block and exposed as _meta.settings:
{"type": "prompt", "name": "get_calculation_prompt", "description": "Ask the calculator well.",
"skill": "SKILL.md", "settings": "settings.json",
"input": {"request": {"type": "string", "description": "the user's arithmetic question"}}}
Turn {{request}} into one call to demo_calculator_tool, then state the result in a sentence.
Both deploy exactly like tools.
New in 1.0: what a package can do
Everything in this section is optional. A repo written for 0.8 loads unchanged and keeps its manifest hash (one
exception: a prompt whose argument already declared an enum now lists it, which changes that hash once). The
helpers come from the runtime that runs your code, so there is nothing to add to requirements.txt:
from ramen_runtime import (text, image, audio, resource, # content
InputRequired, elicit, elicit_url, sample, list_roots, # asking the client
input_responses, request_state, client_capabilities,
MissingCapability, progress)
Content blocks
A tool may return one block or a list of blocks instead of a JSON value:
from ramen_runtime import image, resource, text
def run():
return [
text("Multiple content types test:"),
image(_png(), "image/png"), # bytes in, base64 on the wire
resource("test://mixed-content-resource", text='{"test":"data","value":123}', mime="application/json"),
]
image(data, mime) and audio(data, mime) take bytes. resource(uri, text=… or blob=…, mime="text/plain")
takes exactly one of text and blob. The blocks go into the result's content as given. A block result has no
structuredContent, and a declared output schema is not applied to it. Only what these builders return counts as
a block: a dict you write by hand, {"type": "text", …}, is still JSON-encoded into the result text as in 0.8.
A binary resource
A resource callable that returns bytes is served as a base64 blob instead of text:
{"type": "resource", "name": "bowl_logo", "description": "A binary resource: eight bytes served as a base64 blob.",
"callable": "read", "input": {}, "uri": "ramen://bowl/logo", "mime_type": "application/octet-stream"}
A resource template
A uri that contains {var} is a template. It is listed by resources/templates/list (as uriTemplate) and not
by resources/list, and a resources/read of any matching URI calls the function with the variables as keyword
strings:
{"type": "resource", "name": "bowl_recipe", "description": "A templated resource: the recipe for one flavour.",
"callable": "read", "uri": "ramen://bowl/{flavour}/recipe", "mime_type": "text/plain",
"input": {"flavour": {"enum": ["shoyu", "shio", "miso", "tonkotsu"], "description": "which bowl"}}}
def read(flavour: str) -> str:
return f"recipe for {flavour}"
The rules: the variables in the uri must be exactly the parameters in input, each a string or an enum; a
variable stands for one path segment (it never matches a /) and its value is passed as it appears in the URI; a
value outside a declared enum is "resource not found"; a resource with that exact URI wins over a template. An
enum is also what completion/complete suggests for the variable. Blocking the template by name on the group
page blocks every URI it matches.
A callable prompt
A prompt may name a Python callable instead of a skill file (exactly one of the two):
{"type": "prompt", "name": "pick_prompt", "description": "A callable prompt: order a bowl of the given flavour and size.",
"callable": "build",
"input": {"flavour": {"enum": ["shoyu", "shio", "miso", "tonkotsu"], "description": "which bowl"},
"size": {"type": "string", "description": "small, regular or large"}}}
def build(flavour: str, size: str) -> str:
return f"Order one {size} bowl of {flavour} ramen."
The function gets the declared arguments as keywords and returns a string, one content block, or a list whose items
are strings, blocks, or {"role": …, "content": …} messages. Anything without a role is a user message. Arguments
reach a callable prompt as the client wrote them: a {{$group.VAR}} reference is not resolved, because a
prompt's answer goes back to the client. An argument's enum is listed in prompts/list and is what
completion/complete suggests.
A parameter mirrored in a header
Add "header": "<Name>" to a tool parameter and a 2026-07-28 HTTP client sends that argument in an
Mcp-Param-<Name> request header as well, where a load balancer can read it:
{"type": "tool", "name": "route_tool", "callable": "run",
"input": {
"region": {"type": "string", "description": "mirrored as Mcp-Param-Region", "header": "Region"},
"count": {"type": "integer", "description": "mirrored as Mcp-Param-Count", "header": "Count"},
"note": {"type": "string", "description": "body only"}}}
The tool's code does not change; it still receives the argument from the body. The published inputSchema marks
the property with "x-mcp-header": "Region", which is how a client knows to send the header, and the worker
refuses a call whose header disagrees with the body (Transport → Standard headers).
Only tool parameters of type string, integer, boolean or an enum can have a header (not number). The name
must be a plain HTTP token and unique within the tool, ignoring case; otherwise the package fails to load. Adding,
removing or renaming a header is a breaking change for the deploy's
compatibility gate, because a client holding the old schema would send the wrong headers.
Asking the client for input
Raise InputRequired to ask the client for something and be called again with the answer. The demo repo's
confirm_delete_note:
from ramen_runtime import InputRequired, elicit, input_responses
CONFIRM = {
"type": "object",
"properties": {"confirm": {"type": "boolean", "title": "Delete it?", "description": "true deletes the note"}},
"required": ["confirm"],
}
def confirm_delete(note: str) -> str:
answer = input_responses().get("confirm")
if answer is None:
raise InputRequired({"confirm": elicit(f'Delete the note "{note}"? This cannot be undone.', CONFIRM)})
confirmed = answer.get("action") == "accept" and (answer.get("content") or {}).get("confirm") is True
...
The dictionary's keys are yours; the client answers under the same keys. The function runs again from the top on
the retry, so ask before doing anything with a side effect. The whole flow, the other three kinds of request
(elicit_url, sample, list_roots), carrying state between rounds and what an older client sees are on
Multi round-trip requests.
A form may not ask for a secret. elicit() is refused when a property of its schema is named like a
credential, and the call answers the tool error input request refused: <key>.<field> looks like a secret; use
elicit_url. The check reads the property names of the form, ignoring case:
- refused when the name contains
password,passwd,secret,token,api_key(alsoapi-key,apikey),credentialorcvv: soaccessTokenanddb_passwordare refused; - refused when
cardorssnis a whole word of the name:card_numberandcardNumberare refused,discardis not.
The refusal is an ordinary tool error, so a golden case that expects the tool to ask (or to succeed) fails on it and the mistake stops at the canary.
Saying a client cannot be served
Raise MissingCapability with the capabilities the tool needs; a 2026-07-28 client gets error -32021 naming
them. client_capabilities() returns what this request declared:
from ramen_runtime import MissingCapability, client_capabilities, text
def run():
if "sampling" not in client_capabilities():
raise MissingCapability({"sampling": {}})
return text("has sampling")
Progress
import time
from ramen_runtime import progress, text
def run(steps: int):
for n in range(1, int(steps) + 1):
progress(n, total=int(steps), message=f"step {n}")
time.sleep(0.02)
return text(f"done {steps}")
progress(progress, total=None, message=None) does nothing unless the client asked for progress and can receive
it (Transport → Progress), so it is safe to call always.
A long-running tool
"task": true in a tool's JSON lets a client that speaks the MCP tasks extension get a task id at once and poll
for the result; every other client waits for the answer as before. The demo repo's slow_report:
{"type": "tool", "name": "slow_report", "callable": "report", "task": true,
"input": {"seconds": {"type": "integer", "description": "how long the report takes, in seconds"}},
"output": {"type": "string"}}
Lifecycle, limits and the Redis the zone needs for more than one worker: Tasks.
Apps
An app is a single HTML page a client that speaks MCP Apps (io.modelcontextprotocol/ui, protocol version
2026-07-28) renders in a sandbox next to a tool's result. It lives in mcp/apps/<name>/:
mcp/apps/iris_chart/index.html the page: one file, ≤ 512 KiB, scripts and styles inline
mcp/apps/iris_chart/app.yaml optional: title, description, csp
title: Iris group means
description: Inline SVG bar chart of the per-species means that iris_group_means returns.
csp: # optional; the demo's page is self-contained and declares none
connectDomains: []
resourceDomains: ["https://cdn.example.com"]
The worker serves the page as the resource ui://<group>/<name> with mimeType: text/html;profile=mcp-app; it is
listed by resources/list (with _meta["ui/csp"] when app.yaml sets csp) and read by resources/read like
any resource, blocked by name or URI like any resource. A tool points at an app with "ui": "<name>" in its JSON:
{"type": "tool", "name": "iris_group_means", "callable": "group_means", "ui": "iris_chart", "input": {...}}
The tool then carries _meta["ui/resourceUri"] = "ui://<group>/iris_chart" in tools/list and on every result it
returns, errors and guardrail blocks included; a client that knows the extension fetches the page and hands it the
result. server/discover lists the extension while at least one app is loaded. The rules: the folder name is the
app's name ([A-Za-z0-9][A-Za-z0-9_-]*); index.html must exist and stay under 512 KiB or the app fails to load
with the size in its error; app.yaml knows only title, description and csp (a mapping of lists of strings:
connectDomains, resourceDomains, as the client expects it); a tool whose ui names no loaded app fails to load.
The page is served as written, with no templating; keep every asset inline, and expect to run under
sandbox="allow-scripts" with no credentials. SkillSpector reads the HTML as part of the group's skill text.
Skills
A skill is a folder an agent can install locally, the SKILL.md convention Claude Code and others read. Over
MCP it is the io.modelcontextprotocol/skills extension (2026-07-28). It lives in mcp/skills/<name>/:
mcp/skills/iris-analyst/SKILL.md frontmatter name + description, then the instructions
mcp/skills/iris-analyst/references/*.md anything else beside it: notes, examples, small binaries
---
name: iris-analyst
description: Analyse the Iris data with the iris tools, never fabricating numbers.
---
Call `iris_describe` first, then `iris_outliers`, then `iris_group_means`.
skills/list answers {"skills": [{"name", "description", "version", "files": ["SKILL.md", "references/…"]}]}:
version is the first 12 hex digits of a sha256 over every file in the folder (sorted paths and contents), so it
changes with any edit. Each file is read with resources/read of skill://<name>/<relative path>: UTF-8 files come
back as text (.md is text/markdown), anything else as a base64 blob. The rules: the frontmatter name must
equal the folder name ([A-Za-z0-9][A-Za-z0-9_-]*) and description must be set; every file is ≤ 256 KiB or the
skill fails to load naming the file; symlinks and __pycache__ are not part of a skill; a path that is not in the
skill's files is "not found", one with .. or a leading / is refused. Access follows tools: a skill is gated as
a tool named skills:<name>, so the group page's tool access (list / call per role or key) hides it from
skills/list or refuses its files, and blocking skills:<name> hides it from everyone. The bridge installs a
listed skill into ~/.claude/skills/<name>/ with ramen-mcp-bridge skills install <name>, after a SkillSpector scan
when the group requires one.
Secrets in code
Never put a secret in the repo. The console holds it and the worker renders it at runtime, two ways:
- In a call argument:
{{$demo.OPENAI_API_KEY}}inside any string a client passes is substituted before your function runs. Code can also callramen_runtime.secrets.resolve(text). - In
mcp/env.yaml: flatKEY: valuelines the worker exports to the runtime process at load, with{{$group.SECRET}}references rendered. Tool code readsos.environ["DB_URL"].
A reference with no secret behind it is skipped with a warning. Rendered values are redacted from error messages
and never logged. RAMEN_* names are Ramen's: an env.yaml (or mcp/.env) that sets one fails the deploy at the
sync step, naming the file, line and key (D85). Secrets covers scoping and backends.
Cloud access needs no keys at all. The workers of a zone run as that zone's service account or IAM role, so a
tool that uses google.cloud.storage or boto3 picks that identity up by itself.
Test it before you push
The runtime is a Python package you can run on the folder. It speaks JSON-RPC on stdin and stdout, so one line loads the group and one line calls a tool, exactly as the worker would:
cd ramen/runtime-py && uv sync --all-extras
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"runtime.load","params":{}}' \
'{"jsonrpc":"2.0","id":2,"method":"runtime.call_tool","params":{"name":"demo_calculator_tool","arguments":{"var1":2,"var2":3,"func":"add"}}}' \
| RAMEN_SECRET_DEMO__DB_PASSWORD=x uv run python -m ramen_runtime --bucket /path/to/your-repo 2>/dev/null
{"jsonrpc": "2.0", "id": 1, "result": {"tools": [...], "resources": [...], "prompts": [...], "hash": "...", "errors": [], ...}}
{"jsonrpc": "2.0", "id": 2, "result": {"content": [{"type": "text", "text": "5"}], "isError": false, "structuredContent": {"result": 5}}}
A repo whose mcp/guardrails.yaml names an LLM-backed rail (the demo repo does) answers its guarded calls with
guardrail unavailable: … needs an LLM here, because a local run has no provider; the console supplies one on deploy.
tests/fixtures/proto.schema.json in the Ramen repo is the JSON Schema for the <name>.json files, for a
pre-commit check.
The loop
make upon your laptop. Create a group pointing at your repo, attach zonelocal, deploy.- Call it with the key from the group page, with
curl, themcpSDK or the bridge (Get started). - Push, deploy again, or let GitHub Actions deploy on push. The group page lists what each zone reported, with each tool's schema. The Logs page tails the worker.
Heavy dependencies
The worker pip-installs mcp/requirements.txt on the first load of a new ref. Pin the versions. If the install
fails, the deploy stops at the canary with pip's output in the job log, and the previous version keeps serving.
For heavy stacks such as numpy, pandas or a CUDA wheel, put the dependencies in the image instead. Since 1.0 a
cloud deployment with a builder does that on deploy, from the same requirements.txt; or build an image yourself
and pin it on the group. Both are on Worker images. For such a build (D85) the file may carry
no option line except --require-hashes, --only-binary, --prefer-binary, --pre (and --hash on a
requirement), and no URL, VCS, path or archive requirement; anything else stops the deploy naming the line, unless a
group admin sets build.allow_urls: true on the group (audited).