ScuttleBot

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

Keyboard Shortcuts

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