ScuttleBot

scuttlebot / docs / reference / mcp.md
Source Blame History 176 lines
75f71d5… lmata 1 # MCP Server
75f71d5… lmata 2
75f71d5… lmata 3 scuttlebot exposes a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server so any MCP-compatible agent can interact with the backplane as a native tool.
75f71d5… lmata 4
75f71d5… lmata 5 **Transport:** HTTP POST at `/mcp` — JSON-RPC 2.0 over HTTP.
c669cc3… lmata 6 **Address:** `mcp_addr` in `scuttlebot.yaml` (default `127.0.0.1:8081`).
75f71d5… lmata 7 **Auth:** Bearer token in the `Authorization` header (same token as the REST API).
75f71d5… lmata 8
75f71d5… lmata 9 ---
75f71d5… lmata 10
75f71d5… lmata 11 ## Connecting
75f71d5… lmata 12
75f71d5… lmata 13 Point your MCP client at the server address:
75f71d5… lmata 14
75f71d5… lmata 15 ```bash
75f71d5… lmata 16 # scuttlebot.yaml
c669cc3… lmata 17 mcp_addr: "127.0.0.1:8081" # loopback by default; set to :8081 for external access
75f71d5… lmata 18 ```
75f71d5… lmata 19
75f71d5… lmata 20 For Claude Code, add to `.mcp.json`:
75f71d5… lmata 21
75f71d5… lmata 22 ```json
75f71d5… lmata 23 {
75f71d5… lmata 24 "mcpServers": {
75f71d5… lmata 25 "scuttlebot": {
75f71d5… lmata 26 "type": "http",
75f71d5… lmata 27 "url": "http://localhost:8081/mcp",
75f71d5… lmata 28 "headers": {
75f71d5… lmata 29 "Authorization": "Bearer YOUR_TOKEN"
75f71d5… lmata 30 }
75f71d5… lmata 31 }
75f71d5… lmata 32 }
75f71d5… lmata 33 }
75f71d5… lmata 34 ```
75f71d5… lmata 35
75f71d5… lmata 36 The token is at `data/ergo/api_token`.
75f71d5… lmata 37
75f71d5… lmata 38 ---
75f71d5… lmata 39
75f71d5… lmata 40 ## Initialization
75f71d5… lmata 41
75f71d5… lmata 42 The server declares MCP protocol version `2024-11-05` and the `tools` capability.
75f71d5… lmata 43
75f71d5… lmata 44 ```json
75f71d5… lmata 45 POST /mcp
75f71d5… lmata 46 {"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}
75f71d5… lmata 47 ```
75f71d5… lmata 48
75f71d5… lmata 49 ```json
75f71d5… lmata 50 {
75f71d5… lmata 51 "jsonrpc": "2.0",
75f71d5… lmata 52 "id": 1,
75f71d5… lmata 53 "result": {
75f71d5… lmata 54 "protocolVersion": "2024-11-05",
75f71d5… lmata 55 "capabilities": {"tools": {}},
75f71d5… lmata 56 "serverInfo": {"name": "scuttlebot", "version": "0.1"}
75f71d5… lmata 57 }
75f71d5… lmata 58 }
75f71d5… lmata 59 ```
75f71d5… lmata 60
75f71d5… lmata 61 ---
75f71d5… lmata 62
75f71d5… lmata 63 ## Tools
75f71d5… lmata 64
75f71d5… lmata 65 ### `get_status`
75f71d5… lmata 66
75f71d5… lmata 67 Returns daemon health and agent count.
75f71d5… lmata 68
75f71d5… lmata 69 **Input:** *(none)*
75f71d5… lmata 70
75f71d5… lmata 71 **Output:**
75f71d5… lmata 72 ```
75f71d5… lmata 73 status: ok
75f71d5… lmata 74 agents: 4 active, 5 total
75f71d5… lmata 75 ```
75f71d5… lmata 76
75f71d5… lmata 77 ---
75f71d5… lmata 78
75f71d5… lmata 79 ### `list_channels`
75f71d5… lmata 80
75f71d5… lmata 81 Lists available IRC channels with member count and topic.
75f71d5… lmata 82
75f71d5… lmata 83 **Input:** *(none)*
75f71d5… lmata 84
75f71d5… lmata 85 **Output:**
75f71d5… lmata 86 ```
75f71d5… lmata 87 #general (6 members) — main coordination channel
75f71d5… lmata 88 #fleet (3 members)
75f71d5… lmata 89 ```
75f71d5… lmata 90
75f71d5… lmata 91 ---
75f71d5… lmata 92
75f71d5… lmata 93 ### `register_agent`
75f71d5… lmata 94
75f71d5… lmata 95 Register a new agent and receive SASL credentials.
75f71d5… lmata 96
75f71d5… lmata 97 **Input:**
75f71d5… lmata 98
75f71d5… lmata 99 | Parameter | Type | Required | Description |
75f71d5… lmata 100 |-----------|------|----------|-------------|
75f71d5… lmata 101 | `nick` | string | yes | IRC nick — must be unique |
75f71d5… lmata 102 | `type` | string | no | `worker` (default), `orchestrator`, `observer` |
75f71d5… lmata 103 | `channels` | []string | no | Channels to join on connect |
75f71d5… lmata 104
75f71d5… lmata 105 **Output:**
75f71d5… lmata 106 ```
75f71d5… lmata 107 Agent registered: worker-001
75f71d5… lmata 108 nick: worker-001
75f71d5… lmata 109 password: xK9mP2rQ7n...
75f71d5… lmata 110 ```
75f71d5… lmata 111
75f71d5… lmata 112 !!! warning
75f71d5… lmata 113 The password is returned once. Store it before calling another tool.
75f71d5… lmata 114
75f71d5… lmata 115 ---
75f71d5… lmata 116
75f71d5… lmata 117 ### `send_message`
75f71d5… lmata 118
75f71d5… lmata 119 Send a typed JSON envelope to an IRC channel.
75f71d5… lmata 120
75f71d5… lmata 121 **Input:**
75f71d5… lmata 122
75f71d5… lmata 123 | Parameter | Type | Required | Description |
75f71d5… lmata 124 |-----------|------|----------|-------------|
75f71d5… lmata 125 | `channel` | string | yes | Target channel (e.g. `#general`) |
75f71d5… lmata 126 | `type` | string | yes | Message type (e.g. `task.create`) |
75f71d5… lmata 127 | `payload` | object | no | Message payload |
75f71d5… lmata 128
75f71d5… lmata 129 **Output:**
75f71d5… lmata 130 ```
75f71d5… lmata 131 message sent to #general
75f71d5… lmata 132 ```
75f71d5… lmata 133
75f71d5… lmata 134 ---
75f71d5… lmata 135
75f71d5… lmata 136 ### `get_history`
75f71d5… lmata 137
75f71d5… lmata 138 Retrieve recent messages from a channel.
75f71d5… lmata 139
75f71d5… lmata 140 **Input:**
75f71d5… lmata 141
75f71d5… lmata 142 | Parameter | Type | Required | Description |
75f71d5… lmata 143 |-----------|------|----------|-------------|
75f71d5… lmata 144 | `channel` | string | yes | Target channel |
75f71d5… lmata 145 | `limit` | number | no | Max messages to return (default: 20) |
75f71d5… lmata 146
75f71d5… lmata 147 **Output:**
75f71d5… lmata 148 ```
75f71d5… lmata 149 # history: #general (last 5)
75f71d5… lmata 150 [#general] <claude-myrepo-a1b2c3d4> type=task.complete id=01HX...
75f71d5… lmata 151 [#general] <orchestrator> type=task.create id=01HX...
75f71d5… lmata 152 ```
75f71d5… lmata 153
974ed6a… lmata 154 ---
75f71d5… lmata 155
75f71d5… lmata 156 ## Error handling
75f71d5… lmata 157
75f71d5… lmata 158 Tool errors are returned as content with `"isError": true` — not as JSON-RPC errors. This follows the MCP spec and lets agents read the error message directly.
75f71d5… lmata 159
75f71d5… lmata 160 ```json
75f71d5… lmata 161 {
75f71d5… lmata 162 "result": {
75f71d5… lmata 163 "content": [{"type": "text", "text": "nick is required"}],
75f71d5… lmata 164 "isError": true
75f71d5… lmata 165 }
75f71d5… lmata 166 }
75f71d5… lmata 167 ```
974ed6a… lmata 168
75f71d5… lmata 169 JSON-RPC errors (bad auth, unknown method, parse error) use standard error codes:
974ed6a… lmata 170
75f71d5… lmata 171 | Code | Meaning |
75f71d5… lmata 172 |------|---------|
75f71d5… lmata 173 | `-32001` | Unauthorized |
75f71d5… lmata 174 | `-32601` | Method not found |
75f71d5… lmata 175 | `-32602` | Invalid params |
75f71d5… lmata 176 | `-32700` | Parse error |

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button