---
name: mcp-builder
description: "Build high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when creating MCP servers to integrate external APIs or services, in Python (FastMCP) or TypeScript (MCP SDK)."
user-invocable: true
metadata:
  { "openclaw": { "emoji": "🔌" } }
---

# MCP Server Development Skill

Build MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. The quality of an MCP server is measured by how well it enables an agent to accomplish real-world tasks.

---

## When to Use

Use this skill when Brent asks to:
- Build an MCP server to expose an API or service to an LLM
- Integrate a new external service into the conductor/openclaw ecosystem
- Create tools an agent can use via the MCP protocol

---

## Environment Notes (Conductor-Specific)

- **Preferred language:** TypeScript (MCP SDK) for new servers. Python (FastMCP) for quick integrations where a Python client already exists.
- **Transport:** Streamable HTTP for remote/persistent servers. stdio for local one-shot tools.
- **Deployment target:** Docker container alongside the openclaw stack — follow the existing `docker-compose.yml` pattern in `/var/lib/docker/volumes/openclaw_workspace/_data/infra/openclaw/`.
- **Secret handling:** Secrets go in `/var/lib/docker/volumes/openclaw_workspace/_data/.env` — never hardcoded.
- **MCP registration:** Add the server to `openclaw.json` (`/var/lib/docker/volumes/openclaw_config/_data/openclaw.json`) under the `mcpServers` block once running.

---

## Workflow

### Phase 1 — Research & Plan

1. **Understand the target API** — review docs, auth requirements, key endpoints.
2. **Read MCP best practices:**
   ```bash
   cat /home/node/.openclaw/workspace/skills/mcp-builder/reference/mcp_best_practices.md
   ```
3. **Choose framework and load the relevant guide:**
   ```bash
   # TypeScript (recommended)
   cat /home/node/.openclaw/workspace/skills/mcp-builder/reference/node_mcp_server.md

   # Python
   cat /home/node/.openclaw/workspace/skills/mcp-builder/reference/python_mcp_server.md
   ```
4. **Plan tool surface:** Prioritize comprehensive API coverage. Use consistent prefixes (`service_action`, e.g. `github_create_issue`).

### Phase 2 — Implement

**Project location:** `modules/<service-name>/` in the workspace, or a dedicated repo if standalone.

Key implementation rules:
- Async/await throughout
- Zod (TS) or Pydantic (Python) for input schemas — always include field descriptions
- Actionable error messages that guide the agent toward a solution
- Pagination support where the API paginates
- `readOnlyHint`, `destructiveHint`, `idempotentHint` annotations on every tool
- Return both structured data and human-readable text where possible

### Phase 3 — Review & Test

```bash
# TypeScript — build check
npm run build

# Test with MCP Inspector
npx @modelcontextprotocol/inspector
```

Code quality checklist:
- No duplicated code
- Consistent error handling
- Full type coverage
- Every tool has a clear description and annotated parameters

### Phase 4 — Evaluate

Create 10 evaluation questions covering realistic, complex multi-tool scenarios:
```bash
cat /home/node/.openclaw/workspace/skills/mcp-builder/reference/evaluation.md
```

Output format: XML file with `<evaluation><qa_pair><question>...</question><answer>...</answer></qa_pair></evaluation>`.

### Phase 5 — Register

Add the server to the openclaw gateway config:
```bash
# Read current config
cat /var/lib/docker/volumes/openclaw_config/_data/openclaw.json

# Add under mcpServers block, then restart gateway
cd /var/lib/docker/volumes/openclaw_workspace/_data/infra/openclaw
docker compose up -d --force-recreate openclaw-gateway
```

---

## Reference Files

All reference docs are local — no network fetch needed:

| File | Contents |
|------|----------|
| `reference/mcp_best_practices.md` | Universal MCP guidelines (naming, pagination, transport, security) |
| `reference/node_mcp_server.md` | TypeScript/MCP SDK patterns, project structure, examples |
| `reference/python_mcp_server.md` | Python/FastMCP patterns, Pydantic models, examples |
| `reference/evaluation.md` | Evaluation question format, verification strategy, XML spec |