Skip to content

feat(environment): serve BaseEnvironmentServerWithTools episode tools over MCP - #5349

Merged
ffrujeri merged 4 commits into
ffrujeri/self-contained-shutdown-sweepfrom
ffrujeri/self-contained-mcp
Nov 16, 2026
Merged

ffrujeri merged 4 commits into
ffrujeri/self-contained-shutdown-sweepfrom
ffrujeri/self-contained-mcp

Conversation

@ffrujeri

@ffrujeri ffrujeri commented Oct 30, 2026 •

Copy link
Copy Markdown
Contributor

Stacked on #5348 (shutdown sweep), which is on #5347 (BaseEnvironmentServerWithTools) and #5346 (episode tokens). Review those first; this PR's diff against #5348 is MCP only. The stack: #5346 → #5347 → #5348 → #5349 → #5350 (multi-worker routing).

What changed

A BaseEnvironmentServerWithTools can serve an episode's tools over MCP as well as direct HTTP.

my_environment:
  environment_servers:
    my_environment:
      tool_transports: [mcp]          # or [direct_http] (the default), or both
  • BaseEnvironmentServerWithToolsConfig.tool_transports (on the config class from feat(environment): add BaseEnvironmentServerWithTools, which serves an episode's tools #5347) lists the grants serve_tools returns, in order: direct_http (the default, so existing behavior is unchanged) and/or mcp. The opt-in is not named expose_tools_over_mcp: run_webserver runs Resources Server auto-exposure for any config with that field, which would harvest routes and wrap a /seed_session this server does not have.
  • /mcp is mounted only when mcp is configured, so a server without it never imports the MCP SDK. The grant is an MCPToolAccess named after the server, whose connection points at <server>/mcp with the episode token in X-NeMo-Gym-Episode-Token, the same token as the direct HTTP grant.
  • tools/list shows only the tools of the episode the token names, built from the episode's EpisodeToolset specs, not routes harvested at startup. A missing or invalid token lists no tools.
  • tools/call takes the same path as a direct HTTP call (_episode_for_token, then _run_tool): the same token checks, one call at a time per episode whatever the transport, the same ToolCallRecord ledger, and the same error handling. A refusal (no token, another grant's nonce, an episode that has ended) and a tool error come back as an MCP result with isError: true.
  • MCP tool names: with mcp configured, serve_tools refuses a tool name MCP clients reject, such as one with a dot.
  • Lifespan: /mcp runs its session manager in the app's lifespan, and feat(environment): finish every Environment Server's running cleanups at shutdown #5348's shutdown sweep wraps that lifespan, so at shutdown the MCP manager stops and then the sweep finishes the running episodes' cleanups.
  • nemo_gym/server_runtime/mcp_auto_exposure.py: mount_mcp_endpoint is extracted from install_auto_exposure (the stateless Streamable HTTP manager, the /mcp route and mount, and the lifespan), and _to_result becomes the public to_call_tool_result with an is_error flag. The old name still resolves, with a deprecation warning, through a MOVED_NAMES entry in nemo_gym/_moved_paths.py, as main's import-surface test requires of every name a module had. Resources Server auto-exposure behaves as before.
  • Docs: the Fern MCP guide (environment-tutorials/mcp-resources-server.mdx) gets an "Environment Servers that serve their own tools" section: the tool_transports YAML, which grants each value gives and which agents take them, passing ServedTools.tool_accesses unchanged to the agent's seed, and how a tool's error result reaches the agent over each transport. It says that expose_tools_over_mcp is a different, Resources Server field.

Why

Codex, Pi and Hermes accept only MCP tool grants, so an environment that serves its tools from its Environment Server, instead of a Resources Server, needs MCP to run them (Linear GYMINT-644). BIRD-Interact's a-Interact runs on Codex over MCP today through its Resources Server; this keeps that possible after it moves.

Validation

Command Result
pytest tests/unit_tests/test_moved_paths.py tests/unit_tests/test_public_api.py tests/unit_tests/test_import_linter_coverage.py tests/unit_tests/server_runtime/test_mcp_auto_exposure.py tests/unit_tests/server_runtime/test_checkpoint_resources_mcp.py tests/unit_tests/server_runtime/test_base_environment_server_with_tools.py tests/unit_tests/server_runtime/test_episode_tools.py tests/unit_tests/server_runtime/test_episode_tokens.py tests/unit_tests/server_runtime/test_environment_server.py (after the rebase onto main at dda609f86) 337 passed, including main's import-surface test (test_every_recorded_name_still_resolves_at_its_old_path), which fails without the _to_result entry. Importing base_environment_server does not load the MCP SDK
pytest tests/unit_tests/server_runtime/test_base_environment_server_with_tools.py (after the rebase onto #5348) 36 passed: the tests from #5347 and #5348 on the shared call path and the new config class, the shutdown-sweep test also with /mcp mounted (the MCP manager's lifespan and the sweep both run), plus 11 MCP tests with the MCP SDK's own client (ClientSession over streamablehttp_client) against the app in-process. They cover: the grants for each tool_transports setting share one token; no /mcp without mcp; tools/list shows exactly the episode's tools; an MCP call and a direct HTTP call change the same state and land in one ledger, in order; a missing or garbage token lists no tools and its call is refused; an MCP call after the episode ends is refused; two concurrent episodes each list only their own tools; a dotted tool name is refused; a repeated transport is refused.
Mutation: MCP call_tool calls the toolset directly instead of the shared path test_mcp_lists_the_episodes_tools_and_shares_its_calls_with_direct_http fails (the MCP call is missing from the ledger)
Mutation: list_tools lists every open episode's tools 3 tests fail: missing token, garbage token, and two episodes each listing only their own
pytest tests/unit_tests/server_runtime/test_mcp_auto_exposure.py tests/unit_tests/server_runtime/test_checkpoint_resources_mcp.py tests/unit_tests/server_runtime/test_environment_server.py tests/unit_tests/server_runtime/test_episode_tools.py tests/unit_tests/server_runtime/test_episode_tokens.py (with the test above, at this PR's head after the rebase onto #5348) 172 passed
pytest tests/unit_tests/server_runtime/test_session_routing.py tests/unit_tests/server_runtime/test_checkpoint_participant_workers.py 176 passed
cd fern && npm run check (docs section) 0 errors; 1 warning, a skipped redirect check that needs network access, also without the change
pre-commit run --files on the changed files passed

Rollout evidence

N/A: no environment uses the base class yet. A Codex smoke run over MCP comes with BIRD-Interact's move onto it (Linear GYMINT-646).

Compatibility

@copy-pr-bot

copy-pr-bot Bot commented Oct 30, 2026

Copy link
Copy Markdown

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.

@ffrujeri

Copy link
Copy Markdown
Contributor Author

/ok to test baba7e3

@ffrujeri
ffrujeri force-pushed the ffrujeri/self-contained-mcp branch from baba7e3 to 81a94e0 Compare October 30, 2026 06:19
@ffrujeri
ffrujeri changed the base branch from ffrujeri/self-contained-environment-server to ffrujeri/self-contained-shutdown-sweep October 30, 2026 06:19
@ffrujeri
ffrujeri added this pull request to stack #5352 October 30, 2026 06:21
@ffrujeri

Copy link
Copy Markdown
Contributor Author

/ok to test 81a94e0

@svcnvidia-nemo-ci svcnvidia-nemo-ci added area:env-infra Shared environment framework, lifecycle, registry, scaffolding, and validation feature New capabilities, enhancements, or enablement work labels Oct 30, 2026
@ffrujeri
ffrujeri force-pushed the ffrujeri/self-contained-mcp branch from 81a94e0 to ced94d4 Compare October 30, 2026 16:21
@ffrujeri ffrujeri changed the title feat(environment): serve a self-contained Environment Server's episode tools over MCP feat(environment): serve a turn-based Environment Server's episode tools over MCP Oct 30, 2026
@ffrujeri

Copy link
Copy Markdown
Contributor Author

/ok to test ced94d4

@ffrujeri
ffrujeri force-pushed the ffrujeri/self-contained-mcp branch from ced94d4 to 09d7ce5 Compare October 31, 2026 13:16
@ffrujeri ffrujeri changed the title feat(environment): serve a turn-based Environment Server's episode tools over MCP feat(environment): serve BaseEnvironmentServerWithTools episode tools over MCP Oct 31, 2026
@ffrujeri

Copy link
Copy Markdown
Contributor Author

/ok to test 09d7ce5

ffrujeri added a commit that referenced this pull request Nov 10, 2026
…refuse a token-less MCP listing

Review of #5349:

- With tool_transports [mcp, direct_http], both grants were required,
  and every agent refuses a required grant it cannot use, so no agent
  could take the episode. With both transports, each grant is now
  optional, so each agent takes the one it supports.
- tools/list without a valid episode token returned an empty list, so
  an MCP-only harness that checks only that its server connected ran
  the episode with no tools. It is now a JSON-RPC error.
- Tests cover a broken tool, invalid arguments and another episode's
  tool over MCP: each is an isError result and is recorded as an error.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Felipe Vieira Frujeri <ffrujeri@nvidia.com>
@ffrujeri
ffrujeri force-pushed the ffrujeri/self-contained-mcp branch from 9b3eb26 to 659f7eb Compare November 10, 2026 05:23
@ffrujeri

Copy link
Copy Markdown
Contributor Author

/ok to test 659f7eb

@ffrujeri

Copy link
Copy Markdown
Contributor Author

/ok to test cbede0d

@ffrujeri

Copy link
Copy Markdown
Contributor Author

/ok to test d442eb9

@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

@ffrujeri

Copy link
Copy Markdown
Contributor Author

/ok to test a2fc487

@adil-a

adil-a commented Nov 11, 2026

Copy link
Copy Markdown
Contributor

/review reset=True

@svcnvidia-nemo-ci svcnvidia-nemo-ci left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

SHIP — one documentation NOTE; no confirmed functional regressions found.

I reviewed all five changed files and traced episode authorization, shared call serialization and recording, grant consumers, MCP mounting and cleanup, Resources Server compatibility, and renamed imports. The new guide section addresses the earlier configuration-documentation gap, apart from the current worker limit noted inline.

This was a source-only review. I didn't execute tests or independently verify the validation results reported in the PR.

Review generated by codex. This was a full review. Request a full review with /review reset=true.

@ffrujeri

Copy link
Copy Markdown
Contributor Author

/ok to test 6790cc4

@ffrujeri

Copy link
Copy Markdown
Contributor Author

/ok to test 5e96ace

@ffrujeri

Copy link
Copy Markdown
Contributor Author

/ok to test 63d55fb

@ffrujeri

Copy link
Copy Markdown
Contributor Author

/ok to test 8eec981

@ffrujeri

Copy link
Copy Markdown
Contributor Author

/ok to test c128e50

@ffrujeri

Copy link
Copy Markdown
Contributor Author

/ok to test 0206e88

@ffrujeri

Copy link
Copy Markdown
Contributor Author

/ok to test 957f853

ffrujeri and others added 4 commits November 16, 2026 17:57
… over MCP

Codex, Pi and Hermes accept only MCP tool grants, so a
BaseEnvironmentServerWithTools serves an episode's toolset over MCP as
well.

- BaseEnvironmentServerWithToolsConfig.tool_transports picks the
  grants serve_tools returns: direct_http (the default) and/or mcp.
- With mcp, the server mounts /mcp. tools/list shows only the tools of
  the episode that the X-NeMo-Gym-Episode-Token header names; a missing
  or invalid token lists none.
- An MCP tools/call takes the same path as a direct HTTP call: the same
  token checks, one call at a time per episode, and the same ledger.
- mcp_auto_exposure gains mount_mcp_endpoint, extracted from
  install_auto_exposure, and to_call_tool_result (was _to_result) with
  an is_error flag. Resources Server auto-exposure is unchanged.
- An MCP grant refuses tool names MCP clients reject, such as a dot.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Felipe Vieira Frujeri <ffrujeri@nvidia.com>
…refuse a token-less MCP listing

Review of #5349:

- With tool_transports [mcp, direct_http], both grants were required,
  and every agent refuses a required grant it cannot use, so no agent
  could take the episode. With both transports, each grant is now
  optional, so each agent takes the one it supports.
- tools/list without a valid episode token returned an empty list, so
  an MCP-only harness that checks only that its server connected ran
  the episode with no tools. It is now a JSON-RPC error.
- Tests cover a broken tool, invalid arguments and another episode's
  tool over MCP: each is an isError result and is recorded as an error.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Felipe Vieira Frujeri <ffrujeri@nvidia.com>
… tools over MCP

The MCP guide covered only a Resources Server's expose_tools_over_mcp.
Add a section on BaseEnvironmentServerWithToolsConfig.tool_transports:
the YAML, which grants each value gives and which agents take them,
passing ServedTools.tool_accesses unchanged to the agent's seed, and how
a tool's error result reaches the agent over each transport.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Felipe Vieira Frujeri <ffrujeri@nvidia.com>
… worker

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Felipe Vieira Frujeri <ffrujeri@nvidia.com>
@ffrujeri

Copy link
Copy Markdown
Contributor Author

/ok to test e278016

@github-actions

Copy link
Copy Markdown
Contributor

🔄 Merge queue validation started! You can track the progress here: https://github.com/NVIDIA-NeMo/Gym/actions/runs/43943710542

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:env-infra Shared environment framework, lifecycle, registry, scaffolding, and validation feature New capabilities, enhancements, or enablement work needs-review PR is ready for code review and waiting on a reviewer

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants