NanoClaw MCP Extension

External agent access for NanoClaw via the Model Context Protocol. Contains both the server-side skill (for NanoClaw) and a client extension (for pi.dev).

How it works

External Agent ──SSH tunnel──▶ localhost:3002/mcp
                                     │
                               Bearer token auth
                                     │
                              MCP Channel (mcp:*)
                                     │
                              ┌──────┴──────┐
                              │  GroupQueue  │
                              └──────┬──────┘
                                     │
                         Container Agent (same image,
                         workspace, tools as Telegram)

An MCP server registers as a NanoClaw channel. External agents connect via Streamable HTTP, send messages through the chat tool, and receive the assistant's response. Messages use an isolated mcp:* JID namespace — other channels (Telegram, WhatsApp) see nothing.

Repository Structure

├── nanoclaw-skill/          # Server-side: NanoClaw skill
│   ├── SKILL.md             # Installation instructions
│   ├── src/mcp-server.ts    # MCP server + channel implementation
│   └── modify/              # Intent files for existing file modifications
├── index.ts                 # Client-side: pi.dev extension
├── mcp_test.mjs             # Test scripts
└── README.md

---

Server Setup (NanoClaw)

Option A: Using the NanoClaw skill

If you have Claude Code available:

/add-mcp

Or manually follow the instructions in nanoclaw-skill/SKILL.md.

Option B: Manual installation

1. Install dependencies:

   npm install @modelcontextprotocol/sdk zod
   

2. Copy nanoclaw-skill/src/mcp-server.ts to src/mcp-server.ts

3. Add import '../mcp-server.js'; to src/channels/index.ts

4. Add MCP_API_KEY and MCP_PORT to src/config.ts (see SKILL.md for details)

5. Add MCP server startup to src/index.ts (see SKILL.md for details)

6. Configure .env:

   MCP_API_KEY=<generate with: openssl rand -base64 32>
   MCP_PORT=3002
   

7. Build and restart:

   npm run build
   sudo systemctl restart nanoclaw
   

Security

The MCP server binds to 127.0.0.1 only. Clients connect via SSH tunnel:

ssh -L 3002:localhost:3002 user@your-server -N

---

Client Setup (pi.dev)

Configuration

Set environment variables:

Variable	Required	Default	Description
NANOCLAW_MCP_TOKEN	yes	—	Bearer token (= MCP_API_KEY from server)
NANOCLAW_MCP_URL	no	http://localhost:3002/mcp	MCP server URL

Usage

1. Place the extension in your Pi extensions folder
2. Start the SSH tunnel (if server is remote)
3. Start Pi:

export NANOCLAW_MCP_TOKEN="your-secret-token"
pi

Pi will auto-discover and register the available tools (chat, list_groups).

Generic MCP Client

Any MCP client can connect. Example configuration:

{
  "mcpServers": {
    "nanoclaw": {
      "type": "streamable-http",
      "url": "http://localhost:3002/mcp",
      "headers": {
        "Authorization": "Bearer <MCP_API_KEY>"
      }
    }
  }
}

---

Available MCP Tools

chat

Send a message to the assistant and receive a response.

Parameter	Type	Required	Description
message	string	yes	The message to send
group	string	no	Target group (default: main)

Response time: ~2-3 min cold start, ~5-10s warm (container reuse within idle timeout).

list_groups

Lists available groups. No parameters.

---

Troubleshooting

Symptom	Cause	Fix
Connection refused	SSH tunnel not running	Start tunnel: ssh -L 3002:localhost:3002 ...
401 Unauthorized	Token mismatch	Check MCP_API_KEY in .env matches client token
Slow first response	Cold start	Expected (~2-3 min). Subsequent calls are fast.
(no response)	Container timeout	Check docker logs <container> for errors
MCP server not starting	Missing config	Verify MCP_API_KEY in .env, rebuild, restart