Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions environment_servers/single_agent_turn/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,8 @@ environment_servers:
name: tavily
```

When the tools served to an episode come from several MCP endpoints, each endpoint lists itself under its server's `mcp_server_name`, or else its server's name, and MCP clients name every tool `mcp__<name>__<tool>`. The Environment Server does not start when two granted endpoints list themselves under one name, since their tools would collide.

With partial-rollout checkpointing on, the agent of an episode that grants `mcp` access or any tool server holds an MCP session token that names the episode's attempt, and the Resources Server refuses that token once a restore replaces the attempt. An episode that grants any tool server restarts from its input after a crash instead of continuing from a checkpoint. One that grants only `mcp` access continues from a checkpoint only if its agent borrows the sandbox the Resources seed lent (`sandbox_access`) and re-binds restored sessions to new tool grants (`rebinds_tool_accesses`, as the OpenCode agent does). Otherwise it restarts from its input.

A restore rebuilds a borrowed sandbox under a new ID. When the replacement attempt continues an episode whose agent had not closed yet, it first seeds the Resources and agent sessions again: the Resources Server returns the restored sandbox, and the agent re-binds its restored session to that sandbox and to the replacement attempt's tool grants, such as a new MCP session token. Seeding again is idempotent, so a checkpoint does not wait for it, and a crash during it seeds again after the next restore. An episode without a borrowed sandbox seeds nothing again.
Expand Down
19 changes: 19 additions & 0 deletions environment_servers/single_agent_turn/app.py
Original file line number Diff line number Diff line change
Expand Up @@ -160,6 +160,25 @@ def model_post_init(self, context: Any, /) -> None:
# Fail at startup, not on the first episode, when a tool server cannot serve its tools.
for name in self.tool_server_names:
self._check_tool_server(name, self.config.resources_server.name)
self._check_mcp_server_names()

def _check_mcp_server_names(self) -> None:
"""Refuse a pairing that grants two MCP endpoints listed under one name: MCP clients name each tool by the
endpoint that serves it (``mcp__<name>__<tool>``), so the two endpoints' tools would collide. Each endpoint
lists itself under its ``mcp_server_name``, else its server's name."""
granted = [self.config.resources_server.name] if "mcp" in self.config.resources_tool_transports else []
granted += self.tool_server_names
listed: dict[str, str] = {}
for name in granted:
config = get_first_server_config_dict(self.server_client.global_config_dict, name)
listed_as = config.get("mcp_server_name") or name
if listed_as in listed:
raise ValueError(
f"Environment Server {self.config.name!r} grants the MCP tools of {listed[listed_as]!r} and "
f"{name!r}, which both list themselves as {listed_as!r}, so their tools' names would collide; "
"give one of them another mcp_server_name"
)
listed[listed_as] = name

def _check_tool_server(self, name: str, resources_server_name: str) -> None:
server = f"Environment Server {self.config.name!r}"
Expand Down
51 changes: 47 additions & 4 deletions environment_servers/single_agent_turn/tests/test_app.py
Original file line number Diff line number Diff line change
Expand Up @@ -177,24 +177,27 @@ async def test_the_tasks_agent_context_reaches_the_agent_seed_and_not_the_resour
assert "agent_context" not in client.calls[1][2]["json"]


async def test_single_agent_turn_translates_resources_mcp_metadata_to_canonical_tool_access() -> None:
# The server's own name, and names a resources server's mcp_server_name takes.
@pytest.mark.parametrize("listed_as", ["resources", "company", "company_x", "company-x"])
async def test_single_agent_turn_translates_resources_mcp_metadata_to_canonical_tool_access(listed_as: str) -> None:
environment_server, client = _environment_server(resources_tool_transports=["direct_http", "mcp"])
client.responses[0] = _Response(
{
"resources_session_id": "resources-session",
"resources_tools": {
"server_name": "resources",
"server_name": listed_as,
"headers": {"Authorization": "Bearer scoped"},
},
}
)

await environment_server.run_request(_request())
result = await environment_server.run_request(_request())

assert result.failure is None, result.failure
create_body = AgentSeedSessionRequest.model_validate(client.calls[1][2]["json"])
direct_access, mcp_access = create_body.tool_accesses
assert direct_access.name == "resources.direct_http"
assert mcp_access.name == "resources"
assert mcp_access.name == listed_as
assert mcp_access.required is True
assert mcp_access.connection.transport == "streamable_http"
assert str(mcp_access.connection.url) == "http://resources:8000/mcp"
Expand Down Expand Up @@ -384,6 +387,46 @@ def test_a_server_that_grants_an_mcp_resources_servers_tools_starts(listed_by: s
assert environment_server.tool_server_names == ["search"]


@pytest.mark.parametrize(
("resources_listed_as", "search_listed_as", "transports", "collides"),
[
# Both endpoints are granted over MCP under one name.
("company", "company", ["direct_http", "mcp"], True),
# The tool server takes the resources server's own name.
(None, "resources", ["mcp"], True),
# The resources server's endpoint is not granted over MCP, so only the tool server's is listed.
("company", "company", ["direct_http"], False),
("company", "search_tools", ["mcp"], False),
],
)
def test_a_pairing_that_grants_two_mcp_endpoints_listed_under_one_name_does_not_start(
resources_listed_as: str | None, search_listed_as: str, transports: list, collides: bool
) -> None:
configured, client = _environment_server()
resources = client.global_config_dict.resources.resources_servers.test
resources.update({"expose_tools_over_mcp": True, "mcp_server_name": resources_listed_as})
client.global_config_dict["search"] = {
"resources_servers": {
"tavily_search": {
"host": "search",
"port": 8000,
"entrypoint": "app.py",
"expose_tools_over_mcp": True,
"mcp_server_name": search_listed_as,
}
}
}
config = SingleAgentTurnEnvironmentServerConfig.model_validate(
{**configured.config.model_dump(), "tool_servers": [_SEARCH], "resources_tool_transports": transports}
)

if collides:
with pytest.raises(ValueError, match="'resources' and 'search', which both list themselves as"):
SingleAgentTurnEnvironmentServer(config=config, server_client=client)
else:
assert SingleAgentTurnEnvironmentServer(config=config, server_client=client).tool_server_names == ["search"]


async def test_token_capture_keeps_prefixed_twin_route() -> None:
environment_server, client = _environment_server(token_capture=True)

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -284,6 +284,15 @@ def mcp_allowed_tools_for_session(self, seed_body: dict) -> list[str] | None:

The returned names are signed into that rollout's session token; `tools/list` then advertises only those tools and `tools/call` rejects any other name — per rollout, with no server-wide state.

### An endpoint that sandboxed code calls

When the MCP client runs where the model can read its configuration, such as a harness in a sandbox the resources server lends, two config options make the endpoint an ordinary one:

- `mcp_server_name` is the name the `mcp` metadata gives the endpoint, which clients name its tools by (default: the server's name). It takes letters, digits, `_` and `-`, and starts with a letter or a digit. The Environment Server's MCP grants carry this name, and so do the MCP entries that a sandboxed agent's `tool_servers` seed. Verify-time normalization strips `mcp__<mcp_server_name>__`.
- `mcp_bearer_token: true` hands out the token as `Authorization: Bearer <token>` instead of `X-NeMo-Gym-Session-Token`. `tools/list` then requires the token and lists only the session's tools, and a tool outside the session's grant is answered as an unknown tool. Errors name no framework: a missing or invalid token is `Missing session token (Authorization header).` or `Invalid session token.`, and a tool's HTTP error names the tool rather than its route. It works with clients that pass the metadata's headers as given, as the Environment Server's MCP grants do. The code that reads the token could sign one for another session with the default session key, which anyone can compute from the server's class and name, so the server must override `get_session_secret()` to return a secret; it refuses to start otherwise.

Both options are off by default, and the endpoint then answers as described above.

### Run it

A complete, copy-pasteable run (assumes you saved `app_mcp.py` above). The compose config wires that subclass entrypoint to the agent:
Expand Down
17 changes: 15 additions & 2 deletions nemo_gym/agents/agent_tools.py
Original file line number Diff line number Diff line change
Expand Up @@ -54,8 +54,14 @@ async def seed_mcp_servers(
timeout_s: float,
require_reachable: bool = False,
) -> dict[str, dict[str, object]]:
"""Seed host-side tools; pass only per-session MCP authentication into the sandbox."""
"""Seed host-side tools; pass only per-session MCP authentication into the sandbox.

Each entry is keyed by the name the server's MCP endpoint lists itself under (its seed metadata's
``server_name``, else the server's name), which MCP clients name its tools by. Its URL is the server's.
Two servers listed under one name are refused, since their tools' names would collide.
"""
entries = {}
listed: dict[str, str] = {}
for server in servers:
seeded = await client.post(
server_name=server.name, url_path="/seed_session", json=body.model_dump(), cookies=cookies
Expand All @@ -64,7 +70,14 @@ async def seed_mcp_servers(
metadata = (await get_response_json(seeded)).get(NEMO_GYM_MCP_METADATA_KEY)
if not isinstance(metadata, dict) or not metadata.get("headers"):
raise ValueError(f"Tool server {server.name} must expose authenticated MCP tools")
entries[server.name] = {
listed_as = metadata.get("server_name") or server.name
if listed_as in listed:
raise ValueError(
f"Tool servers {listed[listed_as]!r} and {server.name!r} both list themselves as {listed_as!r}, so "
"their tools' names would collide; give one of them another mcp_server_name"
)
listed[listed_as] = server.name
entries[listed_as] = {
"url": sandbox_server_url(server.name, require_reachable=require_reachable)
+ "/"
+ metadata.get("url_path", "/mcp").lstrip("/"),
Expand Down
61 changes: 51 additions & 10 deletions nemo_gym/server_runtime/base_resources_server.py
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@
# limitations under the License.
import asyncio
import logging
import re
from abc import abstractmethod
from collections import OrderedDict
from collections.abc import AsyncIterator, Mapping
Expand All @@ -38,7 +39,9 @@
ValidationError,
field_validator,
model_serializer,
model_validator,
)
from starlette.datastructures import Headers
from starlette.middleware import Middleware


Expand Down Expand Up @@ -77,7 +80,8 @@
from nemo_gym.server_runtime.base_server import BaseRunServerInstanceConfig, BaseServer, SimpleServer
from nemo_gym.server_runtime.request_handling.model_sampling import CallerSamplingMiddleware
from nemo_gym.server_runtime.request_handling.rollout_context import RolloutContextMiddleware
from nemo_gym.server_runtime.request_handling.session_routing import SessionKind
from nemo_gym.server_runtime.request_handling.session_routing import SessionKind, mcp_session_token
from nemo_gym.server_runtime.tool_access import MCP_TOOL_ACCESS_NAME_PATTERN
from nemo_gym.server_runtime.verifier_observability import observe_verifier
from nemo_gym.telemetry.endpoints import traced_verify_endpoint
from nemo_gym.trajectory.trajectory_record import VerifierInvocation
Expand Down Expand Up @@ -150,6 +154,24 @@ class ReverifyMode(str, Enum):
class BaseResourcesServerConfig(BaseRunServerInstanceConfig):
# Opt in to serve this server's tool routes over MCP; default off.
expose_tools_over_mcp: bool = False
mcp_server_name: Optional[str] = Field(
default=None,
# MCP clients name its tools mcp__<name>__<tool>, from the alphabet of the tools' own names.
pattern=r"^[A-Za-z0-9_-]+$",
description="The name the MCP endpoint lists itself under in /seed_session's MCP metadata, which clients "
"name its tools by (default: this server's name): letters, digits, '_' and '-', starting with a letter "
"or a digit. For an endpoint that code a model can read calls, such as a harness in a sandbox. Needs "
"expose_tools_over_mcp",
)
mcp_bearer_token: bool = Field(
default=False,
description="Hand out MCP session tokens as a standard 'Authorization: Bearer' header instead of "
f"{NEMO_GYM_MCP_SESSION_TOKEN_HEADER}, and require one for tools/list too, which then lists only the "
"session's tools; a tool outside the session's grant is answered as an unknown tool, and errors name no "
"framework. For clients that pass the seed's MCP headers as given, as the environment server's MCP grants "
"do. Needs expose_tools_over_mcp, and a server that overrides get_session_secret(): the server refuses to "
"start when the tokens it hands out are signed with its public session middleware key",
)
session_close_retry_window_seconds: float = Field(
default=300,
gt=0,
Expand All @@ -165,6 +187,28 @@ class BaseResourcesServerConfig(BaseRunServerInstanceConfig):
# The mode of reverification (for gym eval reverify) of this server.
REVERIFY_MODE: ClassVar[ReverifyMode] = ReverifyMode.UNKNOWN

@field_validator("mcp_server_name")
@classmethod
def _mcp_server_name_is_a_grant_name(cls, name: Optional[str]) -> Optional[str]:
"""Refuse a name that no MCP grant takes: an Environment Server grants agents this endpoint under it."""
if name is not None and re.fullmatch(MCP_TOOL_ACCESS_NAME_PATTERN, name) is None:
raise ValueError(
f"{name!r} is not a name an MCP grant takes ({MCP_TOOL_ACCESS_NAME_PATTERN}), and Environment "
"Servers grant agents this endpoint under it"
)
return name

@model_validator(mode="after")
def _mcp_options_need_the_mcp_endpoint(self) -> "BaseResourcesServerConfig":
"""Refuse the MCP endpoint's options on a server that serves no MCP endpoint, where they would do nothing."""
options = [name for name in ("mcp_server_name", "mcp_bearer_token") if getattr(self, name)]
if options and not self.expose_tools_over_mcp:
raise ValueError(
f"{' and '.join(options)} configure this server's MCP endpoint, which it serves only with "
"expose_tools_over_mcp: true"
)
return self


class BaseResourcesServer(BaseServer):
config: BaseResourcesServerConfig
Expand Down Expand Up @@ -1027,16 +1071,12 @@ def _mcp_token_claims(self, scope: dict[str, Any]) -> Optional[MCPTokenClaims]:
``None`` without a token or for one that does not verify; the MCP endpoint rejects a bad token.
An attempt claim that does not decode counts as missing.
"""
header = NEMO_GYM_MCP_SESSION_TOKEN_HEADER.lower().encode()
token = next((value for key, value in scope.get("headers", ()) if key.lower() == header), None)
if token is None:
return None
try:
text = token.decode()
except UnicodeDecodeError:
header = "Authorization" if self.config.mcp_bearer_token else NEMO_GYM_MCP_SESSION_TOKEN_HEADER
text = mcp_session_token(Headers(scope=scope), header)
if text is None:
return None
if self._mcp_token_serializer is None:
self._mcp_token_serializer = mcp_session_token_serializer(self.get_session_middleware_key())
self._mcp_token_serializer = mcp_session_token_serializer(self.get_session_secret())
payload = mcp_session_token_payload(self._mcp_token_serializer, text)
if not isinstance(payload, dict) or not isinstance(payload.get("sid"), str):
return None
Expand Down Expand Up @@ -1102,7 +1142,8 @@ async def delete_external_state(self, kept: frozenset[str]) -> None:

def normalize_tool_name(self, name: str) -> str:
"""Strip this server's MCP namespace from a trajectory tool-call name (see module function)."""
return normalize_tool_name(name, self.config.name or self.__class__.__name__)
# MCP clients namespace tools by the name the endpoint lists itself under
return normalize_tool_name(name, self.config.mcp_server_name or self.config.name or self.__class__.__name__)

def mcp_tools(self, harvested: list["MCPTool"], catchall: Optional[Any]) -> Optional[list["MCPTool"]]:
"""Return the MCP tools to expose (default: the auto-harvested typed POST routes).
Expand Down
Loading
Loading