MCP (Model Context Protocol) servers let your OpenClaw agent interact with external services through standardized tools. Instead of prompt-hacking API calls, you build a clean server that exposes typed tools the agent can call reliably. This guide walks you through building your first MCP server from scratch.

What is MCP?

Standardized protocol

MCP defines a JSON-RPC protocol for LLM-to-tool communication. Your agent discovers available tools, understands their parameters, and calls them with type safety.

Language agnostic

Build servers in Python (FastMCP), TypeScript (MCP SDK), or any language that speaks JSON-RPC over stdio or HTTP.

Composable

Each MCP server handles one domain. Combine multiple servers: one for email, one for calendar, one for smart home.

Quick Start: Python (FastMCP)

Install FastMCP framework

pip install fastmcp

Create a minimal MCP server

# server.py
from fastmcp import FastMCP

mcp = FastMCP("weather")

@mcp.tool()
def get_weather(city: str) -> str:
    """Get current weather for a city."""
    # Your API logic here
    return f"Weather in {city}: 22°C, sunny"

if __name__ == "__main__":
    mcp.run()

# openclaw.config.yaml
mcp_servers:
  weather:
    command: python
    args: [server.py]

Test the tool

openclaw mcp list weather get_weather --city Tokyo

TypeScript Alternative

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "weather", version: "1.0.0" });

server.tool("get_weather",
  { city: z.string().describe("City name") },
  async ({ city }) => ({
    content: [{ type: "text", text: `Weather in ${city}: 22°C` }]
  })
);

const transport = new StdioServerTransport();
await server.connect(transport);

Common Server Patterns

API Wrapper

Wrap REST APIs (GitHub, Jira, Slack) with typed tool definitions. Handle auth, pagination, rate limiting.

get_issues, create_pr, send_message

Database Query

Expose read-only SQL queries. Always use parameterized queries. Never expose write access without approval.

query_customers, get_order_status

IoT Control

Control smart home devices via MQTT or HTTP. Include safety constraints (temperature limits, lock confirmations).

set_thermostat, toggle_lights

File Processor

PDF parsing, image analysis, data transformation. Process files and return structured results.

parse_invoice, extract_table

Security Rules

Never expose write operations without explicit user approval flow
Validate all inputs with schemas (Zod/Pydantic) — never trust LLM output
Use environment variables for API keys, never hardcode
Implement rate limiting to prevent agent-driven API abuse
Log all tool calls for audit trails
Sandbox file system access — restrict to specific directories

Testing Your Server

openclaw mcp list # List registered servers

openclaw mcp list <server> <tool> # Test a specific tool

openclaw logs <server> # View server logs

npx @modelcontextprotocol/inspector # Visual MCP debugger

Troubleshooting

Server won't start

Check stderr: openclaw logs <name>. Common: missing dependencies or wrong Python path.

Tool not discovered

Ensure tool has docstring/description. MCP requires descriptions for tool discovery.

Timeout on tool calls

Default timeout is 30s. Increase with mcp_servers.<name>.timeout: 60 in config.

Agent calls tool incorrectly

Add stricter parameter descriptions and examples. Use Zod/Pydantic for validation.

MCP Server Checklist

✅ Server runs standalone without errors

✅ All tools have clear descriptions and typed parameters

✅ Input validation with Zod/Pydantic schemas

✅ API keys in environment variables

✅ Rate limiting implemented

✅ Error handling returns helpful messages

✅ Registered in openclaw.config.yaml

✅ Tested with openclaw mcp list

What is MCP?

Standardized protocol

MCP defines a JSON-RPC protocol for LLM-to-tool communication. Your agent discovers available tools, understands their parameters, and calls them with type safety.

Language agnostic

Build servers in Python (FastMCP), TypeScript (MCP SDK), or any language that speaks JSON-RPC over stdio or HTTP.

Composable

Each MCP server handles one domain. Combine multiple servers: one for email, one for calendar, one for smart home.

Quick Start: Python (FastMCP)

Install FastMCP framework

pip install fastmcp

Create a minimal MCP server

# server.py
from fastmcp import FastMCP

mcp = FastMCP("weather")

@mcp.tool()
def get_weather(city: str) -> str:
    """Get current weather for a city."""
    # Your API logic here
    return f"Weather in {city}: 22°C, sunny"

if __name__ == "__main__":
    mcp.run()

# openclaw.config.yaml
mcp_servers:
  weather:
    command: python
    args: [server.py]

Test the tool

openclaw mcp list weather get_weather --city Tokyo

TypeScript Alternative

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "weather", version: "1.0.0" });

server.tool("get_weather",
  { city: z.string().describe("City name") },
  async ({ city }) => ({
    content: [{ type: "text", text: `Weather in ${city}: 22°C` }]
  })
);

const transport = new StdioServerTransport();
await server.connect(transport);

Common Server Patterns

API Wrapper

Wrap REST APIs (GitHub, Jira, Slack) with typed tool definitions. Handle auth, pagination, rate limiting.

get_issues, create_pr, send_message

Database Query

Expose read-only SQL queries. Always use parameterized queries. Never expose write access without approval.

query_customers, get_order_status

IoT Control

Control smart home devices via MQTT or HTTP. Include safety constraints (temperature limits, lock confirmations).

set_thermostat, toggle_lights

File Processor

PDF parsing, image analysis, data transformation. Process files and return structured results.

parse_invoice, extract_table

Security Rules

Never expose write operations without explicit user approval flow

Validate all inputs with schemas (Zod/Pydantic) — never trust LLM output

Use environment variables for API keys, never hardcode

Implement rate limiting to prevent agent-driven API abuse

Log all tool calls for audit trails

Sandbox file system access — restrict to specific directories

Troubleshooting

Server won't start

Check stderr: openclaw logs <name>. Common: missing dependencies or wrong Python path.

Tool not discovered

Ensure tool has docstring/description. MCP requires descriptions for tool discovery.

Timeout on tool calls

Default timeout is 30s. Increase with mcp_servers.<name>.timeout: 60 in config.

Agent calls tool incorrectly

Add stricter parameter descriptions and examples. Use Zod/Pydantic for validation.

MCP Server Checklist

✅ Server runs standalone without errors

✅ All tools have clear descriptions and typed parameters

✅ Input validation with Zod/Pydantic schemas

✅ API keys in environment variables

✅ Rate limiting implemented

✅ Error handling returns helpful messages

✅ Registered in openclaw.config.yaml

✅ Tested with openclaw mcp list

MCP Server Building Guide

What is MCP?

Standardized protocol

Language agnostic

Composable

Quick Start: Python (FastMCP)

TypeScript Alternative

Common Server Patterns

API Wrapper

Database Query

IoT Control

File Processor

Security Rules

Testing Your Server

Troubleshooting

MCP Server Checklist

▶ Related Resources

MCP Server Building Guide

What is MCP?

Standardized protocol

Language agnostic

Composable

Quick Start: Python (FastMCP)

TypeScript Alternative

Common Server Patterns

API Wrapper

Database Query

IoT Control

File Processor

Security Rules

Testing Your Server

Troubleshooting

MCP Server Checklist

▶ Related Resources