How to Use McpClient to Connect External Agents to DimOS Blueprints

The McpClient module acts as a bridge between external LLM-based agents and running DimOS blueprints by exposing blueprint skills as JSON-RPC tools via the Modular Control Protocol (MCP).

The dimensionalOS/dimos repository provides a complete MCP implementation that allows external agents to discover and invoke skills exposed by running blueprints. By combining the McpServer module embedded in the blueprint with the McpClient connector, you enable any HTTP-capable client to control robot behaviors through a standardized JSON-RPC interface.

Understanding the MCP Architecture

The DimOS MCP implementation follows a client-server pattern where the blueprint exposes capabilities and external agents consume them.

McpServer Implementation

McpServer runs inside the blueprint as a FastAPI-based JSON-RPC endpoint. According to dimos/agents/mcp/mcp_server.py, it registers all @skill decorated methods from connected modules via on_system_modules (lines 10-15) and serves them through three standard MCP protocol methods.

McpClient Implementation

McpClient connects to this endpoint, discovers available tools, and wraps them as LangChain StructuredTool instances. As implemented in dimos/agents/mcp/mcp_client.py, the client handles the initialization handshake, tool discovery, and LLM agent orchestration, enabling external agents to interact with blueprint capabilities.

Configuring the MCP Server in Your Blueprint

To expose a blueprint to external agents, you must compose it with McpServer.blueprint() alongside your robot stack and the MCP client.

Blueprint Composition

# dimos/robot/unitree/go2/blueprints/agentic/unitree_go2_agentic_mcp.py

from dimos.agents.mcp.mcp_client import mcp_client
from dimos.agents.mcp.mcp_server import McpServer
from dimos.core.blueprints import autoconnect

unitree_go2_agentic_mcp = autoconnect(
    unitree_go2_spatial,
    McpServer.blueprint(),   # Exposes @skill methods via HTTP JSON-RPC

    mcp_client(),            # Connects external LLM agent

    _common_agentic,
)

Server Startup and Configuration

When the blueprint starts, the server initializes on the port defined by GlobalConfig.mcp_port (default 9990). As shown in lines 68-78 of dimos/agents/mcp/mcp_server.py, the FastAPI application launches and exposes the JSON-RPC endpoint at /mcp.

JSON-RPC Endpoint Methods

The server implements three core MCP methods:

• initialize (lines 77-85): Returns protocol version and server capabilities during the handshake phase.
• tools/list (lines 88-100): Enumerates all exposed skills as JSON schema tool definitions, enabling clients to discover available capabilities.
• tools/call (lines 103-135): Receives tool invocation requests, forwards arguments to the underlying skill methods, and returns results following the MCP content schema.

Setting Up the McpClient Connection

The client requires a McpClientConfig pointing to the server URL to establish communication.

Client Configuration

from dimos.agents.mcp.mcp_client import McpClient, McpClientConfig

config = McpClientConfig(mcp_server_url="http://localhost:9990/mcp")
client = McpClient(config=config)

Tool Discovery and Agent Creation

During on_system_modules, the client executes a retry loop calling initialize until the server responds (lines 19-31 in dimos/agents/mcp/mcp_client.py). It then requests tools/list to fetch the JSON schema of every available skill (lines 102-118).

Each discovered tool is wrapped in a LangChain StructuredTool that knows how to invoke tools/call on the server (lines 33-60). Finally, create_agent builds a LangChain agent using these tools and the configured LLM model (default gpt-4o) as shown in lines 81-86.

Routing Messages Between Agents and Blueprints

Human commands enter through the human_input In-stream, typically via the DimOS CLI:

dimos run unitree_go2_agentic_mcp
dimos agent-send "walk forward 2 meters then wave"

As implemented in dimos/agents/mcp/mcp_client.py (lines 66-70), these messages convert to HumanMessage objects and process in a background thread. The LLM agent decides which skills to invoke, calling them through the MCP server. Responses publish to the agent Out-stream (lines 16-20) for downstream modules or CLI display.

Connecting External Agents Without LangChain

Any HTTP client can interact directly with the MCP server, bypassing the LangChain agent layer entirely. This is useful for external agents that only need to invoke specific skills rather than perform LLM reasoning.

import httpx
import json
import uuid

MCP_URL = "http://localhost:9990/mcp"

def jsonrpc(method, params=None):
    payload = {
        "jsonrpc": "2.0",
        "id": str(uuid.uuid4()),
        "method": method,
        "params": params or {}
    }
    resp = httpx.post(MCP_URL, json=payload)
    resp.raise_for_status()
    return resp.json()["result"]

# 1. Handshake

jsonrpc("initialize")

# 2. Discover available tools

tools = jsonrpc("tools/list")["tools"]
move_tool = next(t for t in tools if t["name"] == "move")

# 3. Invoke a specific skill directly

result = jsonrpc(
    "tools/call",
    {"name": "move", "arguments": {"x": 0.5, "duration": 3.0}}
)
print(result)  # Returns MCP content schema with execution results

This approach allows external scripts, monitoring systems, or alternative agent frameworks to control DimOS blueprints using standard HTTP POST requests.

Summary

• McpServer exposes blueprint @skill methods via HTTP JSON-RPC on the port specified by GlobalConfig.mcp_port, implementing the three core MCP protocol methods (initialize, tools/list, tools/call).
• McpClient discovers these tools using the initialization handshake and tools/list endpoint, wrapping them as LangChain StructuredTool instances for LLM agent integration.
• Message flow travels through human_input and agent streams, with the client handling LLM reasoning and skill invocation via the MCP server.
• External agents can bypass the LangChain layer and call tools/call directly via HTTP POST requests to control blueprint behaviors without importing DimOS agent dependencies.

Frequently Asked Questions

What is the default URL for connecting McpClient to a running blueprint?

By default, the MCP server listens on http://localhost:9990/mcp. You can configure this by setting the mcp_server_url parameter in McpClientConfig when instantiating the client, or by modifying GlobalConfig.mcp_port to change the server-side binding.

Can I use McpClient to connect external agents without using LangChain?

Yes. While the built-in McpClient uses LangChain for agent orchestration, external agents can interact directly with the JSON-RPC endpoint. Any HTTP client can call initialize, tools/list, and tools/call to discover and invoke skills without importing LangChain or the DimOS agent framework.

How does the client handle server startup delays?

The McpClient implements a retry loop in its on_system_modules method (lines 19-31 in dimos/agents/mcp/mcp_client.py) that repeatedly calls initialize until the server responds successfully. This ensures the client waits gracefully for the blueprint to fully start and the MCP server to become available before proceeding with tool discovery.

Which blueprint modules expose their skills to the MCP server?

Any module containing @skill decorated methods that registers via on_system_modules automatically exposes those methods through the MCP server. The server introspects these modules during startup and generates JSON schema tool definitions for the tools/list response, making all registered skills available to external clients.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}