feat: gym_tool dual registration — every tool served over both HTTP and MCP from one declaration

[adil-a]

Closes #1749.

What this PR does

One gym_tool declaration now serves a tool through both doors: a plain HTTP POST /<name>
route (what simple_agent calls) and an MCP tool on a /mcp endpoint (what MCP-native agents
like Claude Code call). The separate MCPResourcesServer class is gone — MCP is a lazy capability
of SimpleResourcesServer, activated only when a server actually declares a tool, so the 78
tool-less servers are untouched. All 16 servers that execute tools over HTTP are migrated; both
transports resolve the same per-rollout session, and verifiers score rollouts identically
regardless of which door the agent used. Of the +4.7k inserted lines, +3.5k are tests;
production code is ~+1.1k, ~600 of it in one file.

How to review (suggested order)

Commits are review-ordered (base → agent fix → example migration → docs → one server per commit →
perf → simplification → verifier normalization → test dedup), and every intentional behavior
delta is named in its server's commit message — nothing changes silently.

1. nemo_gym/base_resources_server.py — the whole mechanism. Path through it: the gym_tool
   docstring (the user manual: decorator form for hand-written tools, runtime call form for
   registry/discovered tools, three input_schema modes) → setup_webserver (the lazy gate that
   keeps tool-less servers untouched) → _setup_mcp (builds both doors; re-registers the MCP
   SDK's low-level list/call handlers) → _register_http_gym_tool (the HTTP twin).
2. resources_servers/example_single_tool_call/app.py — the PR in miniature. Diff it against
   main: the hand-written route registration and request model collapse into one @gym_tool.
3. One server per migration pattern (the rest repeat): math_advanced_calculations (typed
   methods), workplace_assistant (runtime-registered registry tools), newton_bench
   (model-described tools — also fixes a real pre-existing bug where a failed directory scan
   silently dropped tool registration).
4. tests/unit_tests/test_gym_tool_dual_registration.py — the contract as executable spec
   (handshake, raw-argument fidelity, session parity, seed augmentation, transport parity).
5. Skim: claude_code_agent (logging fix), the fern tutorial rewrite, nemo_gym/mcp_test_utils.py
   (shared test scaffolding).

Contract changes vs main, and why

Change	Why
MCPResourcesServer deleted (breaking)	One entry point was the goal; an alias would silently make isinstance checks true for every server. Failure mode is a loud ImportError with a 2-line fix.
seed_session responses on tool-bearing servers gain an additive mcp key (server name, /mcp path, signed session token)	MCP agents need per-rollout connection info; injected automatically with setdefault semantics — a server returning its own mcp value is never overwritten. Tool-less servers unchanged.
POST to an unknown tool path: 404 body now lists available tools (servers with historical 200-error-string contracts keep them via a handle_unknown_tool override)	Agents feed response bodies back to the model as tool output; a body naming valid tools lets the model self-correct.
Non-POST to an unknown tool path: 404 → 405	Side effect of the POST-only catch-all; 405 is the semantically correct status and no agent sends non-POST to tool routes.
Non-empty malformed JSON body to a lax tool: 422, tool not dispatched (empty body still tolerated as no-args)	Differential testing caught the original migration dispatching tools on garbage input (stepping an env, mutating reward state). Restores main's behavior.
Verifiers normalize trajectory tool names via a new normalize_tool_name helper	MCP agents record calls as mcp__<server>__<tool>; HTTP agents record bare names. Without normalization an identical, correct Claude-over-MCP rollout scored 0.0 (reproduced, then fixed and regression-tested). Bare names pass through untouched, so HTTP scoring is byte-identical.
A typed tool whose only parameter is a Pydantic model is rejected at startup	That shape is ambiguous (callers could nest under the parameter name or send the model's fields flat); the error names the fix: @gym_tool(input_schema=<Model>). The check runs in the collection chokepoint so no registration path can bypass it.
mcp dependency pin tightened <2 → <1.29	The base re-registers the SDK's low-level tools/list/tools/call handlers via private attrs (mcp._mcp_server) — required because FastMCP's own call path silently drops undeclared argument names (verified against SDK source), which would corrupt registry tools' calls. Private-attr coupling means the ceiling should move deliberately, gated on the handshake test suite.

Deliberate decisions (please don't re-litigate without new evidence)

• allowed_tools (per-session tool visibility) gates MCP only; HTTP is unrestricted status quo.
  Enforcing it on HTTP would change recorded behavior of a published benchmark
  (indirect_prompt_injection). Over MCP — a brand-new surface — each session lists and can call
  exactly its task's tools, carried as a claim inside the signed stateless token (works across
  workers, nothing to evict).
• Error shapes differ per transport by design (MCP: isError tool result on HTTP 200; HTTP:
  status codes) — documented in the gym_tool docstring and the tutorial.
• Wire-byte preservation was the migration acceptance bar: all 14 dispatcher/route-migrated
  servers' HTTP request/response bytes, including error paths, are replay-tested against recorded
  bytes (indirect_prompt_injection is covered by contract tests preserving its soft-error
  strings; example_mcp_weather had no pre-existing HTTP tool surface).
• indirect_prompt_injection's MCP surface advertises permissive object schemas (its per-task
  schemas live in dataset rows, which remain the model-facing truth; one MCP tool name can carry
  only one schema). MCP there is strictly tighter than HTTP, never looser — owner sign-off
  requested above.

Runnable example — workspace env driven by Claude Code over MCP

workplace_assistant's 27 tools are MCP-callable with configuration only — no further server
changes needed. Compose config
(save as workplace_claude.yaml):

workplace_assistant:
  resources_servers:
    workplace_assistant:
      entrypoint: app.py
      domain: agent

workplace_claude:
  responses_api_agents:
    claude_code_agent:
      entrypoint: app.py
      resources_server:
        type: resources_servers
        name: workplace_assistant
      model: claude-sonnet-4-6
      anthropic_api_key: ${anthropic_api_key}   # from repo-root env.yaml

# env.yaml:  anthropic_api_key: sk-ant-...
gym env start --config workplace_claude.yaml

gym eval run --no-serve \
  --agent workplace_claude \
  --input resources_servers/workplace_assistant/data/example.jsonl \
  --output results/workplace_claude_rollouts.jsonl --limit 1

A correct rollout shows Claude Code calling mcp__workplace_assistant__email_search_emails then
mcp__workplace_assistant__email_reply_email, and reward: 1.0. (Any Anthropic-format endpoint
works via the agent's anthropic_base_url config field.)

30-second smoke test without an LLM (same server, both doors, one session):

import requests
s = requests.Session()
meta = s.post("http://127.0.0.1:<port>/seed_session", json={}).json()["mcp"]
token = meta["headers"]["X-NeMo-Gym-Session-Token"]
# HTTP door
print(s.post("http://127.0.0.1:<port>/company_directory_find_email_address", json={"name": "carlos"}).json())
# MCP door (same session, via the token)
print(s.post(f"http://127.0.0.1:<port>{meta['url_path']}",
    headers={"Accept": "application/json, text/event-stream", "X-NeMo-Gym-Session-Token": token},
    json={"jsonrpc": "2.0", "id": 1, "method": "tools/call",
          "params": {"name": "company_directory_find_email_address", "arguments": {"name": "carlos"}}}).json())

How this was verified

All 14 route-migrated servers were differentially byte-replayed against main (happy + error
paths mined from datasets) — the only intentional deltas are exactly the contract-table rows above.
Live end-to-end with real models: reward 1.0 over both transports (workplace_assistant and
example_mcp_weather, via gym env start + gym eval run). Tool-less servers proven
byte-identical, with a subprocess test asserting mcp is never imported for them. Transport parity
(unfiltered MCP tools/list == HTTP tool routes) is a tested invariant per server. 194 new tests;
base-file coverage 99%.

Migrating your own env: full patterns in
fern/versions/latest/pages/environment-tutorials/mcp-resources-server.mdx (added in this PR).

🤖 Generated with Claude Code

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[adil-a]

/ok to test 161a44d

[github-actions]

🌿 Preview your docs: https://nvidia-preview-mcp-dual-registration.docs.buildwithfern.com/nemo/gym

Here are the markdown pages you've updated:

• nemo/gym/environment-tutorials/mcp-resources-server

[adil-a]

/ok to test 3b4bb9d

[adil-a]

/ok to test 1e40fd6

[ffrujeri]

.The review-ordered commits and the contract table in the description made it easier to follow, and serving each tool over both HTTP and MCP from one @gym_tool declaration is a reasonable unification. The core mechanism holds up under scrutiny: session threading across both transports, the raw-argument dispatch that deliberately bypasses FastMCP's argument-dropping, the per-transport error contracts, and the 99% base-file coverage all check out.

Background (for reviewers new to this surface)

• Model Context Protocol (MCP) — spec: https://modelcontextprotocol.io
• Official MCP Python SDK this builds on (FastMCP; the base re-registers the SDK's low-level mcp._mcp_server list/call handlers): https://github.com/modelcontextprotocol/python-sdk — pinned mcp>=1.27,<1.29, verified against 1.28.0.

Where this sits

Every resources server inherits SimpleResourcesServer, so this changes a shared contract: the seed_session response (an additive mcp key carrying a signed per-rollout session token), tool dispatch, per-transport error shapes, and verifier tool-name handling. Both transports resolve the same per-rollout session id; verifiers normalize_tool_name so MCP-namespaced (mcp__<server>__<tool>) and bare HTTP names score identically.

flowchart LR
    Model[Model Server] -->|tool-call decisions| SA[simple_agent]
    Model -->|tool-call decisions| CC[claude_code_agent]
    SA -->|"POST /<name> (args)"| HTTP
    CC -->|"POST /mcp · tools/call"| MCP
    subgraph RS[SimpleResourcesServer]
      GT["@gym_tool"] -.->|registers at startup| HTTP[HTTP twin]
      GT -.->|registers at startup| MCP[MCP twin + raw dispatch]
      HTTP -->|writes state under session id| ST[(per-rollout session)]
      MCP -->|writes state under session id| ST
      ST -->|read at scoring| VER["verify()<br/>normalize_tool_name"]
      SEED[seed_session]
    end
    SEED -->|"mcp key: /mcp path + signed token"| CC
    VER -->|reward| RL[(reward profiling / training)]

Loading

Solid arrows: runtime data flow (label = what moves). Dashed arrows: startup-time registration.

One design alternative worth a note in the docs

Was route auto-exposure considered as an alternative to explicit declarations — e.g. fastapi-mcp-style introspection of existing FastAPI routes, or a hook on route registration that publishes every custom route as an MCP tool, so authors don't wrap anything? Reading the migrated set, that approach covers only the easy half: typed-route servers introspect cleanly, but the dispatcher/registry servers (workplace_assistant's 27 registry tools, ns_tools' POST /{tool_name}, math_advanced_calculations' /{path}, indirect_prompt_injection's per-task schemas) have no per-tool routes to introspect — their schemas live in registries and dataset rows, so some per-tool declaration carrying {name, description, input_schema} is unavoidable there, which is what gym_tool's runtime-call form is.

Any auto-exposure design does need one exclusion mechanism: verify/seed_session/aggregate_metrics are structurally indistinguishable from tools (POST routes with a single Pydantic body model), so introspection alone can't tell them apart. A static denylist of the reserved routes handles that cleanly — it's the same set this PR already maintains as RESERVED_MCP_TOOL_NAMES, and fastapi-mcp ships the equivalent as exclude_operations. So exclusion is solvable; the structural limitation is really the dispatcher/registry half above. (fastapi-mcp 0.2.0 also rides SSE, which Streamable HTTP is replacing.)

Two small asks come out of this: it would be worth capturing the "why not auto-expose routes?" rationale briefly in the tutorial so the question has a durable answer; and if zero-wrapping ever matters for external authors, an opt-in helper that introspects a subclass's typed routes and registers them through gym_tool internally would be clean follow-up sugar on top of this mechanism (a sketch, not a request for this PR). For what it's worth, the byte-replay tests establish the wire payloads didn't change — the migration cost is authoring shape only.

A follow-up suggestion: env lifecycle vs tools (Gymnasium lens)

The migration surfaces a contract question worth a follow-up issue: for environment-shaped servers, which operations are tools (model-facing affordances) and which are reserved lifecycle (harness-facing, like seed_session/verify)? The classic Gym/Gymnasium contract gives a principled split — reset() ↔ seed_session, step(action) ↔ a tool, close() ↔ reserved lifecycle — and openenv in this PR already ships step as a gym_tool. But who triggers teardown differs per server today:

• math_with_code.end_session / newton_bench.end_session are @gym_tools — cleanup runs only if the model decides to call it, and the teardown button is advertised in tools/list on both transports;
• openenv.verify() hand-codes cleanup inline — which quietly makes verify destructive: its reward falls back to 0.0 when the session is gone, so a second verify call on the same rollout scores 0.0 instead of the true reward (scoring and episode-end are fused);
• unmigrated env wrappers like aviary use a separate /close route the harness must know to call — the right shape, but per-server convention rather than contract.

Suggestion for the follow-up: promote close to a base-provided reserved endpoint, mirroring how this PR treats seed_session. Servers never write the route — they implement a close_session(session_id) hook (idempotent, never in tools/list), and the base routes POST /close into it, resolving the session id from the same signed cookie verify already uses. The agent harness calls it once in its common rollout path (a finally after verify); an idle-expiry sweep in the base backstops crashed or non-compliant harnesses by calling the same hook:

sequenceDiagram
    participant AG as Agent harness
    participant RS as Resources server (base)
    participant SUB as Subclass

    AG->>RS: POST /seed_session          (reset)
    AG->>RS: tool calls                   (step — HTTP or MCP)
    AG->>RS: POST /verify                 (score — pure, repeatable)
    RS->>SUB: verify(body) → reward
    AG->>RS: POST /close (session cookie) — finally-block after verify
    RS->>SUB: close_session(session_id)   — base-routed hook
    Note over RS,SUB: idle-expiry sweep also calls close_session()<br/>— backstop for crashed rollouts / non-compliant harnesses

Loading

This keeps verify pure (repeatable scoring, no teardown latency or failures inside the scoring response), matches the Gymnasium contract exactly, and still guarantees cleanup via the sweep. A nice detail: no migrated server declares a tool named close, so close can join RESERVED_MCP_TOOL_NAMES cleanly — unlike retrofitting end_session, which would break the two servers above at startup. Rounding out the contract: step-style action tools should pass the env's action schema via input_schema= rather than a weak step(**anything) signature, and openenv's accumulate-then-verify() reward adapter becomes the documented pattern (minus the inline close). This also sharpens the auto-exposure question above: an env's step is legitimately a tool while its close never should be — the line becomes contractual instead of a per-server accident. None of this needs to happen in this PR.

The inline notes are small: two doc-accuracy points (the allowed_tools wording and the /mcp trust-boundary note) and a defensive fix for _model_from_json_schema. Nothing blocking from my side. Nice work.

[ffrujeri]

nemo_gym/base_resources_server.py:544

The MCP-only scope of allowed_tools is clearly deliberate (per the PR description) and this isn't re-litigating it — it's about the token-validation path within MCP. When X-NeMo-Gym-Session-Token is missing or fails signature verification, _mcp_session_claims(required=False) returns (None, None), so this call-gate and the tools/list filter are skipped: a tokenless client sees all tools and can call any stateless one (stateful tools still raise via require_mcp_session_id()). Not model-reachable — the harness sets the header — and with HTTP unrestricted by design there's no marginal exposure, so this is a docs-accuracy point: the class docstring, build_mcp_session_metadata, and the tutorial describe allowed_tools as restricting "which tools an MCP session can list and call," which reads as enforcement. Consider describing it as cooperative per-session scoping — and since test_garbage_token_lists_everything suggests the fail-open is intended, worth stating that explicitly in the docstring.

[ffrujeri]

fern/versions/latest/pages/environment-tutorials/mcp-resources-server.mdx:165

Small doc-accuracy point: describing /mcp as "protected by the per-rollout session token" conflates session binding with authentication. The token's signing key is deterministic (ClassName___config.name) and DNS-rebinding protection is disabled here, so the real boundary is network isolation — the token binds a request to a rollout session, it isn't a secret. This is the same trust model as the pre-existing signed session cookie (so not a new concern), but a one-line note that /mcp must not face untrusted networks would set expectations correctly.

[ffrujeri]

nemo_gym/base_resources_server.py:741

Two edge cases here for validate=True dict-schema tools: a property using the standard nullable form "type": ["string", "null"] makes dict.get([...]) raise TypeError: unhashable type: 'list' at startup (the server fails to boot), and an integer/number enum or $ref with no explicit "type" is coerced to str, so a valid int argument is wrongly 422'd over HTTP. Only openenv uses validate=True today (and its own _json_type_to_python shares the crash), so impact is low, but guarding list/non-str type values would harden the helper for other dict-schema authors:

Suggested change

	python_type = type_map.get(prop.get("type", "string"), str)
	prop_type = prop.get("type", "string")
	if isinstance(prop_type, list): # nullable form ["string", "null"] — first non-null wins
	prop_type = next((t for t in prop_type if t != "null"), "string")
	python_type = type_map.get(prop_type, str)