# How to Use McpClient to Connect External Agents to DimOS Blueprints

> Learn how to use McpClient to connect external agents to DimOS blueprints. Expose blueprint skills as JSON-RPC tools and integrate LLM-based agents seamlessly.

- Repository: [Dimensional/dimos](https://github.com/dimensionalOS/dimos)
- Tags: how-to-guide
- Published: 2026-03-15

---

**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`](https://github.com/dimensionalOS/dimos/blob/main/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`](https://github.com/dimensionalOS/dimos/blob/main/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

```python

# 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`](https://github.com/dimensionalOS/dimos/blob/main/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

```python
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`](https://github.com/dimensionalOS/dimos/blob/main/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:

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

```

As implemented in [`dimos/agents/mcp/mcp_client.py`](https://github.com/dimensionalOS/dimos/blob/main/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.

```python
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`](https://github.com/dimensionalOS/dimos/blob/main/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.