[RFC 003] [1/n] Implement basic local MCP server & add MCP client #224

Darktex · 2025-11-25T02:16:56Z

As part of implementing RFC 003, I'm adding support for MCP.

At Meta, we typically work with Stacked PRs as a way to stay sane and allow for easier review.

For this reason, this is just the first PR in the stack, but it is already adding the MCP functionality.

Implementation Phases:

PR 1 (Current): Core MCP infrastructure + echo_env conversion
PR 2 (Future): Migrate remaining environments
PR 3 (Future): CodeAct environment with MCP integration
PR 4 (Future): Fix double marshaling with callable introspection

Darktex · 2025-11-25T02:18:21Z

rfcs/RFC-003-implementation-journal.md

@@ -0,0 +1,329 @@
+# RFC-003 Implementation Journal


This was written by Claude. Keeping this here while I implement, but I will remove it when the stack lands.

Darktex · 2025-11-25T02:19:52Z

src/envs/echo_env/client.py



-class EchoEnv(HTTPEnvClient[EchoAction, EchoObservation]):
+class EchoEnv(HTTPEnvClient[CallToolAction, Observation]):


For now I followed the HTTPEnvClient convention, but to me this is the weakest part of OpenEnv as we require that people write boilerplate that we can generate for them.

I will tackle this when we go into supporting ToolCall and CodeAct at the same time, as that is a natural fit for generating this boilerplate on the fly.

Darktex · 2025-11-25T02:20:45Z

src/core/env_server/mcp_environment.py

+        Raises:
+            ValueError: If MCP client not configured or action type invalid
+        """
+        from .types import CallToolObservation, ListToolsObservation


Claude this, but me no like. Will fix.

Darktex · 2025-11-25T02:21:26Z

src/core/env_server/http_server.py

-            observation = await loop.run_in_executor(
-                self._executor, self.env.step, action
-            )
+            # Handle MCP actions asynchronously (don't use thread pool for async operations)


@pankit-eng this is where I need your eyes the most. Does this make sense?

Copilot

Pull request overview

This PR implements the core MCP (Model Context Protocol) infrastructure for OpenEnv as the first phase of RFC-003. It introduces a new MCPEnvironment base class that allows environments to expose tools via the MCP protocol, and converts the echo_env as a reference implementation. The changes enable both gym-style orchestration through HTTP endpoints and direct MCP JSON-RPC access for production agents.

Key Changes:

Added MCP action types (ListToolsAction, CallToolAction) and corresponding observations to the core type system
Implemented MCPEnvironment base class that handles MCP client/server communication boilerplate
Extended HTTP server with /mcp JSON-RPC endpoint for direct tool access alongside existing /step endpoint
Refactored echo_env to use MCP pattern, replacing custom EchoAction/EchoObservation with MCP tools

Reviewed changes

Copilot reviewed 15 out of 17 changed files in this pull request and generated 16 comments.

Show a summary per file

File	Description
`src/core/env_server/types.py`	Added MCP action and observation types (`ListToolsAction`, `CallToolAction`, `ListToolsObservation`, `CallToolObservation`)
`src/core/env_server/mcp_environment.py`	New base class providing MCP infrastructure for environments
`src/core/env_server/http_server.py`	Added `/mcp` JSON-RPC endpoint and MCP action routing in `/step` handler
`src/core/env_server/__init__.py`	Exported new MCP types and `MCPEnvironment` class
`src/core/pyproject.toml`	Added `mcp` and `fastmcp` dependencies
`src/envs/echo_env/server/mcp_server.py`	New MCP tool definitions for echo environment
`src/envs/echo_env/server/echo_environment.py`	Refactored to extend `MCPEnvironment` instead of custom implementation
`src/envs/echo_env/server/app.py`	Updated to use base `Action`/`Observation` types for MCP support
`src/envs/echo_env/models.py`	Removed custom `EchoAction` and `EchoObservation` (deprecated in favor of MCP)
`src/envs/echo_env/client.py`	Updated to handle MCP actions and parse MCP observations
`src/envs/echo_env/__init__.py`	Removed exports of deprecated custom action/observation types
`tests/core/mcp/test_mcp.py`	New test file for MCP client/server integration
`examples/test_mcp_integration.py`	Integration test script demonstrating MCP usage
`examples/echo_mcp_demo.py`	Demo script showing MCP tool interaction
`rfcs/RFC-003-implementation-journal.md`	Implementation journal documenting decisions and progress

Comments suppressed due to low confidence (1)

src/core/env_server/http_server.py:17

Import of 'json' is not used.

import json

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review for a chance to win a $100 gift card. Take the survey.

Copilot · 2025-11-25T02:24:16Z

src/core/env_server/http_server.py

+            Returns:
+                JSON-RPC 2.0 response
+            """
+            if self.env.mcp_client is None:


The /mcp endpoint assumes self.env.mcp_client exists, but not all Environment instances will have this attribute. This will raise an AttributeError for non-MCP environments. Add a hasattr(self.env, 'mcp_client') check or check if the env is an instance of MCPEnvironment first.

Suggested change

if self.env.mcp_client is None:

if not hasattr(self.env, "mcp_client") or self.env.mcp_client is None:

@pankit-eng this is good catch by copilot. Do you think we should just add that line?

Copilot · 2025-11-25T02:24:17Z

src/envs/echo_env/client.py

+        >>> tools = client.list_tools()
+        >>> print(tools)  # [{"name": "echo_message", ...}]
+        >>>
+        >>> # Call echo_message tool
+        >>> result = client.echo_message("Hello!")
+        >>> print(result["echoed_message"])  # "Hello!"


The docstring mentions list_tools() and echo_message() methods that are not implemented in the EchoEnv class. Either implement these convenience methods or update the documentation to reflect the actual API (using step() with ListToolsAction and CallToolAction).

Copilot · 2025-11-25T02:24:17Z

examples/echo_mcp_demo.py

+
+    # List available tools
+    print("2. Listing available tools...")
+    tools = client.list_tools()


The list_tools() method is not implemented in the EchoEnv client class (see client.py). This call will fail with an AttributeError. Either implement the method in the client or use the step() method with a ListToolsAction.

Copilot · 2025-11-25T02:24:17Z

examples/echo_mcp_demo.py

+
+    # Call echo_message tool using convenience method
+    print("3. Calling echo_message tool...")
+    result = client.echo_message("Hello from MCP!")


The echo_message() method is not implemented in the EchoEnv client class (see client.py). This call will fail with an AttributeError. Either implement the method in the client or use the step() method with a CallToolAction.

Copilot · 2025-11-25T02:24:17Z

src/core/env_server/http_server.py

+                    "id": None,
+                }
+
+            body = await request.json()


The /mcp endpoint lacks error handling for malformed JSON. If request.json() fails (e.g., invalid JSON in request body), it will raise an exception. Consider wrapping the await request.json() call in a try-except block and returning a JSON-RPC error with code -32700 ("Parse error") for invalid JSON.

Copilot · 2025-11-25T02:24:19Z

src/core/env_server/http_server.py

+            return CallToolAction(
+                tool_name=action_data["tool_name"],


Accessing action_data["tool_name"] will raise a KeyError if the tool_name field is missing from the request. Use action_data.get("tool_name") with an appropriate error message if it's None, or validate that the field exists before accessing it.

Suggested change

return CallToolAction(

tool_name=action_data["tool_name"],

tool_name = action_data.get("tool_name")

if tool_name is None:

raise ValueError("Missing required field 'tool_name' for CallToolAction")

return CallToolAction(

tool_name=tool_name,

Copilot · 2025-11-25T02:24:19Z

src/core/env_server/http_server.py

+
+            try:
+                # Reuse MCP client from environment (avoids creating duplicate client)
+                async with self.env.mcp_client:


The MCP client is being used within an async with block in the /mcp endpoint (line 168) and also in _handle_mcp_action (mcp_environment.py line 133). This could lead to issues if the client doesn't support being entered multiple times concurrently. Consider whether the client should be managed at the environment level or if each endpoint should manage its own context.

Copilot · 2025-11-25T02:24:19Z

src/core/env_server/mcp_environment.py

+
+        self.mcp_server = mcp_server
+        self.mcp_client = Client(mcp_server)
+        super().__init__(mcp_client=self.mcp_client)


The Environment.__init__ base class doesn't accept an mcp_client parameter. This call will fail with a TypeError. The base class __init__ signature is def __init__(self, transform: Transform | None = None) (see interfaces.py line 95).

Either:

Remove the mcp_client=self.mcp_client argument here, or

Update the Environment.__init__ signature to accept mcp_client as an optional parameter

Suggested change

super().__init__(mcp_client=self.mcp_client)

super().__init__()

Copilot · 2025-11-25T02:24:19Z

src/envs/echo_env/client.py

+    from core.env_server.types import (
+        CallToolAction,
+        CallToolObservation,
+        ListToolsAction,
+        ListToolsObservation,
+        Observation,
+        State,
+    )


Import of 'ListToolsAction' is not used.

Copilot · 2025-11-25T02:24:20Z

src/envs/echo_env/client.py

+    from openenv_core.env_server.types import (
+        CallToolAction,
+        CallToolObservation,
+        ListToolsAction,
+        ListToolsObservation,
+        Observation,
+        State,
+    )


Import of 'ListToolsAction' is not used.

Darktex · 2025-11-25T19:05:20Z

@copilot I accept all your suggestions. Can you implement these changes?

Copilot · 2025-11-25T19:05:30Z

@Darktex I've opened a new pull request, #226, to work on those changes. Once the pull request is ready, I'll request review from you.

pankit-eng · 2025-11-30T13:51:18Z

src/core/env_server/types.py

See if we can rename the file name and not use types.py. It starts conflicting usually.

Yeah good point

pankit-eng · 2025-12-01T18:22:08Z

examples/echo_mcp_demo.py

+
+    # Reset the environment
+    print("1. Resetting environment...")
+    result = client.reset()


is resetting a pre-req to list_tools call? Or in other words, does reset() semantically have any impact on the list_tools?

Keep in mind that list_tools() should be removed since instead we are just going to allow env.step(ListToolsAction()). Apart from that, hmmm I think that we may still want you to call .reset() first to initialize the env, in case some of your tools require state (e.g. a driving sim)

pankit-eng · 2025-12-01T18:30:33Z

src/core/env_server/types.py

+    Contains the list of available tools with their schemas.
+    """
+
+    tools: List[Dict[str, Any]] = field(default_factory=list)


@Darktex - can we use a strongly types schema(openAPI or similar) like how MCP list/tools does.
Each ToolSpec is defined as:

{ name: string; // Unique identifier for the tool description?: string; // Human-readable description inputSchema: { // JSON Schema for the tool's parameters type: "object", properties: { ... } // Tool-specific parameters } }

And this API returns a list of the above typed object:

[ToolSpec]

Good callout

pankit-eng · 2025-12-01T18:35:42Z

src/core/env_server/types.py

    metadata: Dict[str, Any] = field(default_factory=dict)


+@dataclass(kw_only=True)


I would strongly recommend that we create typed objects for tools and use that in client as well as the server:

@dataclass class Tool: name: str description: str input_schema: Dict[str, Any] output_schema: Dict[str, Any]

pankit-eng · 2025-12-01T18:47:54Z

src/core/env_server/types.py

+    Contains the result of calling a tool, or an error if the call failed.
+    """
+
+    result: Optional[Any] = None


All fields must be required for a CallToolObservation. Lets remove optional

We should be specific about error here: error coming from the tool execution needs to be part of the result object and not the error field. In other words, we should assume that tool will bundle the error in the Result and we will return the same as is in the result field.

For any other errors including but not limited to - invalid args, transport level issue, etc.., we can have an error field as we have here. Error field could also be more expanded:

class Error: error_type: enum error_str: description ....

pankit-eng · 2025-12-01T18:52:00Z

src/core/env_server/mcp_environment.py

+        from fastmcp import Client
+
+        self.mcp_server = mcp_server
+        self.mcp_client = Client(mcp_server)


I would imagine that we will need to support multiple mcp servers and hence, multiple mcp clients in one environment. Are you planning on adding the routing support in a separate PR for the same?

@pankit-eng Correct! For now, let's do a single, local MCP server

* Initial plan * Address code review feedback from copilot-pull-request-reviewer Co-authored-by: Darktex <[email protected]> * Address secondary code review comments Co-authored-by: Darktex <[email protected]> * Remove list_tools and echo_message convenience methods per review feedback Co-authored-by: Darktex <[email protected]> * Address code review feedback: add import examples and use isinstance Co-authored-by: Darktex <[email protected]> * Remove unnecessary isinstance check in echo_mcp_demo.py Co-authored-by: Darktex <[email protected]> --------- Co-authored-by: copilot-swe-agent[bot] <[email protected]> Co-authored-by: Darktex <[email protected]>

Darktex · 2025-12-01T21:18:20Z

@copilot Can you send me a PR implementing Pankit's comments?

Copilot · 2025-12-01T21:18:30Z

@Darktex I've opened a new pull request, #230, to work on those changes. Once the pull request is ready, I'll request review from you.

[1/n] Implement RFC 003

84a2919

Darktex requested review from Copilot, pankit-eng and zkwentz November 25, 2025 02:16

meta-cla bot added the CLA Signed This label is managed by the Meta Open Source bot. label Nov 25, 2025

Copilot started reviewing on behalf of Darktex November 25, 2025 02:17 View session

Darktex commented Nov 25, 2025

View reviewed changes

Copilot finished reviewing on behalf of Darktex November 25, 2025 02:22

Copilot AI reviewed Nov 25, 2025

View reviewed changes

Copilot AI mentioned this pull request Nov 25, 2025

Address code review feedback for MCP implementation #226

Merged

16 tasks

pankit-eng reviewed Nov 30, 2025

View reviewed changes

pankit-eng requested changes Dec 1, 2025

View reviewed changes

Copilot AI mentioned this pull request Dec 1, 2025

Add strongly typed MCP types: Tool, ToolError, rename types.py to mcp_types.py #230

Draft

13 tasks



		class EchoEnv(HTTPEnvClient[EchoAction, EchoObservation]):
		class EchoEnv(HTTPEnvClient[CallToolAction, Observation]):

	if self.env.mcp_client is None:
	if not hasattr(self.env, "mcp_client") or self.env.mcp_client is None:

-            return CallToolAction(
-                tool_name=action_data["tool_name"],
+            tool_name = action_data.get("tool_name")
+            if tool_name is None:
+                raise ValueError("Missing required field 'tool_name' for CallToolAction")
+            return CallToolAction(
+                tool_name=tool_name,

	super().__init__(mcp_client=self.mcp_client)
	super().__init__()

		metadata: Dict[str, Any] = field(default_factory=dict)


		@dataclass(kw_only=True)

[RFC 003] [1/n] Implement basic local MCP server & add MCP client #224

Are you sure you want to change the base?

[RFC 003] [1/n] Implement basic local MCP server & add MCP client #224

Uh oh!

Conversation

Darktex commented Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Nov 25, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 25, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 25, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 25, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 25, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 25, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 25, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 25, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 25, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 25, 2025

Choose a reason for hiding this comment

Uh oh!

Darktex commented Nov 25, 2025

Uh oh!

Copilot AI commented Nov 25, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Darktex commented Dec 1, 2025

Uh oh!

Copilot AI commented Dec 1, 2025

Darktex commented Nov 25, 2025 •

edited

Loading