feat(mcp): add mcp client and server (#1300)

* Moving towards deprecating `Agent`. It has been efectivelly split between `McpClient` and `McpServer`.
* McpServer exposes all the `@skill` functions as MCP tools.
* McpClient starts a langchain agent which coordinates calling tools from McpServer.
* McpClient is not strictly necessary. You can register the MCP server in claude code and make it call tools.
* McpClient also listens to `/human_input` so it can be used through the `humancli` like `Agent` can.

Author: paul-nechifor

.gitignore

@@ -69,3 +69,5 @@ yolo11n.pt
 
 CLAUDE.MD
 /assets/teleop_certs/
+
+/.mcp.json

dimos/agents/agent.py

@@ -46,9 +46,8 @@ class AgentConfig(ModuleConfig):
     model_fixture: str | None = None
 
 
-class Agent(Module):
-    default_config: type[AgentConfig] = AgentConfig
-    config: AgentConfig
+class Agent(Module[AgentConfig]):
+    default_config = AgentConfig
     agent: Out[BaseMessage]
     human_input: In[str]
     agent_idle: Out[bool]

dimos/agents/conftest.py

@@ -31,11 +31,6 @@
 FIXTURE_DIR = Path(__file__).parent / "fixtures"
 
 
-@pytest.fixture
-def fixture_dir() -> Path:
-    return FIXTURE_DIR
-
-
 @pytest.fixture
 def agent_setup(request):
     coordinator = None

dimos/agents/mcp/README.md

@@ -0,0 +1,55 @@
+# DimOS MCP Server
+
+Expose DimOS robot skills to Claude Code via Model Context Protocol.
+
+## Setup
+
+```bash
+uv sync --extra base --extra unitree
+```
+
+Add to Claude Code (one command)
+
+```bash
+claude mcp add --transport http --scope project dimos http://localhost:9990/mcp
+```
+
+Verify that it was added:
+
+```bash
+claude mcp list
+```
+
+## MCP Inspector
+
+If you want to inspect the server manually, you can use MCP Inspector.
+
+Install it:
+
+```bash
+npx -y @modelcontextprotocol/inspector
+```
+
+It will open a browser window.
+
+Change **Transport Type** to "Streamable HTTP", change **URL** to `http://localhost:9990/mcp`, and **Connection Type** to "Direct". Then click on "Connect".
+
+## Usage
+
+**Terminal 1** - Start DimOS:
+```bash
+uv run dimos run unitree-go2-agentic-mcp
+```
+
+**Claude Code** - Use robot skills:
+```
+> move forward 1 meter
+> go to the kitchen
+> tag this location as "desk"
+```
+
+## How It Works
+
+1. `McpServer` in the blueprint starts a FastAPI server on port 9990
+2. Claude Code connects directly to `http://localhost:9990/mcp`
+3. Skills are exposed as MCP tools (e.g., `relative_move`, `navigate_with_text`)

dimos/protocol/mcp/__init__.py dimos/agents/mcp/__init__.pydimos/protocol/mcp/__init__.py renamed to dimos/agents/mcp/__init__.py

@@ -0,0 +1,103 @@
+# Copyright 2026 Dimensional Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import os
+from pathlib import Path
+from threading import Event
+
+from dotenv import load_dotenv
+from langchain_core.messages.base import BaseMessage
+import pytest
+
+from dimos.agents.agent_test_runner import AgentTestRunner
+from dimos.agents.mcp.mcp_client import McpClient
+from dimos.agents.mcp.mcp_server import McpServer
+from dimos.core.blueprints import autoconnect
+from dimos.core.global_config import global_config
+from dimos.core.transport import pLCMTransport
+
+load_dotenv()
+
+FIXTURE_DIR = Path(__file__).parent / "fixtures"
+
+
+@pytest.fixture
+def agent_setup(request):
+    coordinator = None
+    transports: list[pLCMTransport] = []
+    unsubs: list = []
+    recording = bool(os.getenv("RECORD"))
+
+    def fn(
+        *,
+        blueprints,
+        messages: list[BaseMessage],
+        dask: bool = False,
+        system_prompt: str | None = None,
+        fixture: str | None = None,
+    ) -> list[BaseMessage]:
+        history: list[BaseMessage] = []
+        finished_event = Event()
+
+        agent_transport: pLCMTransport = pLCMTransport("/agent")
+        finished_transport: pLCMTransport = pLCMTransport("/finished")
+        transports.extend([agent_transport, finished_transport])
+
+        def on_message(msg: BaseMessage) -> None:
+            history.append(msg)
+
+        unsubs.append(agent_transport.subscribe(on_message))
+        unsubs.append(finished_transport.subscribe(lambda _: finished_event.set()))
+
+        # Derive fixture path from test name if not explicitly provided.
+        if fixture is not None:
+            fixture_path = FIXTURE_DIR / fixture
+        else:
+            fixture_path = FIXTURE_DIR / f"{request.node.name}.json"
+
+        client_kwargs: dict = {"system_prompt": system_prompt}
+
+        if recording or fixture_path.exists():
+            client_kwargs["model_fixture"] = str(fixture_path)
+
+        blueprint = autoconnect(
+            *blueprints,
+            McpServer.blueprint(),
+            McpClient.blueprint(**client_kwargs),
+            AgentTestRunner.blueprint(messages=messages),
+        )
+
+        global_config.update(
+            viewer_backend="none",
+            dask=dask,
+        )
+
+        nonlocal coordinator
+        coordinator = blueprint.build()
+
+        if not finished_event.wait(60):
+            raise TimeoutError("Timed out waiting for agent to finish processing messages.")
+
+        return history
+
+    yield fn
+
+    if coordinator is not None:
+        coordinator.stop()
+
+    for transport in transports:
+        transport.stop()
+
+    for unsub in unsubs:
+        unsub()

dimos/agents/mcp/conftest.py

@@ -0,0 +1,34 @@
+{
+  "responses": [
+    {
+      "content": "",
+      "tool_calls": [
+        {
+          "name": "register_user",
+          "args": {
+            "name": "Paul"
+          },
+          "id": "call_NrrizXSIFaeCLuG9i05IwDy3",
+          "type": "tool_call"
+        }
+      ]
+    },
+    {
+      "content": "",
+      "tool_calls": [
+        {
+          "name": "register_user",
+          "args": {
+            "name": "paul"
+          },
+          "id": "call_2QPx4GsL61Xjrggbq7afXTjn",
+          "type": "tool_call"
+        }
+      ]
+    },
+    {
+      "content": "The user named 'paul' has been registered successfully.",
+      "tool_calls": []
+    }
+  ]
+}

dimos/agents/mcp/fixtures/test_can_call_again_on_error[False].json

@@ -0,0 +1,34 @@
+{
+  "responses": [
+    {
+      "content": "",
+      "tool_calls": [
+        {
+          "name": "register_user",
+          "args": {
+            "name": "Paul"
+          },
+          "id": "call_XSy1Dx1dGtQv5zPaEJtb2hd7",
+          "type": "tool_call"
+        }
+      ]
+    },
+    {
+      "content": "",
+      "tool_calls": [
+        {
+          "name": "register_user",
+          "args": {
+            "name": "paul"
+          },
+          "id": "call_aYFug1g3TATnaYus9HUVxoQS",
+          "type": "tool_call"
+        }
+      ]
+    },
+    {
+      "content": "The user named \"paul\" has been registered successfully.",
+      "tool_calls": []
+    }
+  ]
+}

dimos/agents/mcp/fixtures/test_can_call_again_on_error[True].json

@@ -0,0 +1,22 @@
+{
+  "responses": [
+    {
+      "content": "",
+      "tool_calls": [
+        {
+          "name": "add",
+          "args": {
+            "x": 33333,
+            "y": 100
+          },
+          "id": "call_RssRDDd9apDjNoVLz4jRLVk0",
+          "type": "tool_call"
+        }
+      ]
+    },
+    {
+      "content": "The result of 33333 + 100 is 33433.",
+      "tool_calls": []
+    }
+  ]
+}

dimos/agents/mcp/fixtures/test_can_call_tool[False].json

@@ -0,0 +1,22 @@
+{
+  "responses": [
+    {
+      "content": "",
+      "tool_calls": [
+        {
+          "name": "add",
+          "args": {
+            "x": 33333,
+            "y": 100
+          },
+          "id": "call_pzzddF9mBynGYZVdCmGHOB5V",
+          "type": "tool_call"
+        }
+      ]
+    },
+    {
+      "content": "The result of 33333 + 100 is 33433.",
+      "tool_calls": []
+    }
+  ]
+}