Architecture

Overview

RobotMCP has three layers: the server that hosts the MCP endpoint, modules that provide tools, and the cloud that handles setup. Once running, all traffic flows directly between the LLM client and your local server — the cloud is not in the data path.

┌──────────────────────────────────────────────────────────┐
│  LLM Client (Claude, ChatGPT, Gemini)                    │
└──────────────────────┬───────────────────────────────────┘
                       │ MCP over HTTPS
                       V
┌──────────────────────────────────────────────────────────┐
│  Cloudflare Tunnel ({your-robot}.robotmcp.ai)            │
└──────────────────────┬───────────────────────────────────┘
                       │
                       V
┌──────────────────────────────────────────────────────────┐
│  RobotMCP Server (localhost:8766)                        │
│  ┌────────────────────────────────────────────────────┐  │
│  │  OAuth 2.1 middleware (optional)                   │  │
│  ├────────────────────────────────────────────────────┤  │
│  │  MCP endpoint (/mcp)                               │  │
│  ├────────────────────────────────────────────────────┤  │
│  │  Module auto-discovery & registration              │  │
│  ├──────────────┬──────────────┬──────────────────────┤  │
│  │  ROS-MCP     │  Module B    │  Module C ...        │  │
│  │  Module      │              │                      │  │
│  └──────┬───────┴──────────────┴──────────────────────┘  │
└─────────┼────────────────────────────────────────────────┘
          │ WebSocket
          V
┌──────────────────────────────────────────────────────────┐
│  rosbridge (port 9090) > ROS / ROS2                      │
└──────────────────────────────────────────────────────────┘

RobotMCP Server

The server is a FastAPI application that exposes an MCP endpoint and manages modules. It runs locally on your machine or directly on the robot.

Endpoints:

Endpoint	Transport	Description
POST /mcp	Streamable HTTP	Primary MCP endpoint (recommended)
GET /sse	SSE	Legacy endpoint for older clients
GET /	HTTP	Server info

Key responsibilities:

• Module auto-discovery — on startup, scans .gitmodules, reads each module's pyproject.toml, auto-installs dependencies, and calls the module's register() function
• Cloudflare tunnel — exposes the local server as {your-robot}.robotmcp.ai with no port forwarding or firewall changes
• OAuth 2.1 — optional authentication with PKCE, dynamic client registration, and creator-only access control
• CLI daemon — runs as a background process with commands for start, stop, status, and verify

Modules

Modules are plug-in packages that register tools, resources, and prompts with the server. The server discovers them automatically as git submodules.

How modules work

Each module provides an integration.py with a register() function:

from fastmcp import FastMCP

def register(mcp: FastMCP, **kwargs) -> None:
    @mcp.tool()
    def my_tool(param: str) -> str:
        """Description of what this tool does."""
        return f"Result: {param}"

At startup, the server:

1. Parses .gitmodules to find all modules
2. Reads each module's pyproject.toml to get the package name
3. Installs dependencies via pip install -e
4. Calls register(mcp) to add the module's tools to the server

ROS-MCP Module

The ROS-MCP module is the primary module, included by default. It connects to ROS/ROS2 via rosbridge and exposes the following tools:

Tool category	Capabilities
Topics	Publish messages, subscribe to streams, list available topics
Services	Call any service including custom types
Parameters	Read and write ROS parameters
Nodes	List and inspect running nodes
Actions	ROS action support
Images	Capture and analyze camera feeds
Connection	Manage rosbridge connections
Robot config	Retrieve robot specifications

It also registers resources (topic definitions, service schemas, type documentation) and prompts (system prompts for data analysis, debugging, and robot interaction).

Creating your own module

A module needs two files:

my-module/
├── pyproject.toml       # Package name and dependencies
└── my_module/
    ├── __init__.py
    └── integration.py   # register(mcp, **kwargs) function

pyproject.toml:

[project]
name = "my-module"
version = "0.1.0"
dependencies = ["fastmcp>=2.0.0"]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

Add it to the server:

robotmcp-server add https://github.com/robotmcp/test-mcp-server.git

For the full guide, including how to organize tools into categories, register resources and prompts, handle configuration via environment variables, and test your module, see the submodule integration guide.

RobotMCP Cloud

A lightweight service at app.robotmcp.ai that handles one-time setup:

• User authentication (via Supabase)
• Cloudflare tunnel creation and DNS configuration
• Server sharing and access management via the web dashboard

The cloud service is only involved during initial setup and server management. It is never in the MCP data path — once configured, LLM clients connect directly to your local server through the Cloudflare tunnel.