https://github.com/ironlain88/the-agents-mcp
MCP server for The Agents — connect Claude Code, Cursor, or any MCP client to the visualization hub.
https://github.com/ironlain88/the-agents-mcp
ai-agents claude-code cursor mcp mcp-server model-context-protocol npm-package visualization
Last synced: 3 months ago
JSON representation
MCP server for The Agents — connect Claude Code, Cursor, or any MCP client to the visualization hub.
- Host: GitHub
- URL: https://github.com/ironlain88/the-agents-mcp
- Owner: IronLain88
- License: mit
- Created: 2026-02-25T16:58:07.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-03-26T18:06:42.000Z (3 months ago)
- Last Synced: 2026-03-27T05:52:25.426Z (3 months ago)
- Topics: ai-agents, claude-code, cursor, mcp, mcp-server, model-context-protocol, npm-package, visualization
- Language: TypeScript
- Homepage: https://the-agents.net
- Size: 179 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# The Agents — MCP Server
*The middleman between your AI doing all the work and you watching it happen in pixel art*
[](https://www.npmjs.com/package/the-agents-mcp)
[](./LICENSE)
[](https://github.com/IronLain88/The-Agents-MCP/actions/workflows/ci.yml)
```jsonc
// .mcp.json
{
"mcpServers": {
"agent-visualizer": {
"command": "npx",
"args": ["the-agents-mcp"],
"env": { "HUB_URL": "http://localhost:4242", "AGENT_NAME": "Claude" }
}
}
}
```
---
MCP server that connects AI agents to [The Agents Hub](https://github.com/IronLain88/The-Agents-Hub). Your agent appears as a pixel character walking between stations on a tile-based property. Finally, proof that *someone* is working on your project.
Works with **Claude Code**, **Cursor**, and any MCP-compatible client. Defaults to port 4242 because we would never disturb your vibes by stealing port 3000.
## Quick Start
### 1. Start the hub
```bash
docker run -p 4242:4242 zer0liquid/the-agents-hub:latest
```
Or [run from source](https://github.com/IronLain88/The-Agents-Hub).
### 2. Add to your MCP config
Add to your project's `.mcp.json`:
```json
{
"mcpServers": {
"agent-visualizer": {
"command": "npx",
"args": ["the-agents-mcp"],
"env": {
"HUB_URL": "http://localhost:4242",
"AGENT_NAME": "Claude",
"AGENT_SPRITE": "Yuki"
}
}
}
}
```
### 3. Open the viewer
Go to **http://localhost:4242/viewer/** and watch your agent work.
## Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `HUB_URL` | `http://localhost:4242` | Hub server URL |
| `API_KEY` | *(none)* | Hub API key for authenticated endpoints |
| `AGENT_ID` | auto-generated | Unique agent identifier |
| `AGENT_NAME` | `Agent` | Display name on the property |
| `AGENT_SPRITE` | `Kael` | Character sprite name |
| `OWNER_ID` | auto from git | Property owner ID |
| `OWNER_NAME` | auto from git | Property owner display name |
## Tools
### State
| Tool | Description |
|------|-------------|
| `update_state` | Set agent state — character walks to matching station. Common: `thinking`, `planning`, `reading`, `searching`, `writing_code`, `writing_text`, `idle` |
| `update_subagent_state` | Report a subagent's state (renders as smaller character) |
| `set_name` | Change display name at runtime |
| `get_village_info` | Property summary: stations, signals, boards, inbox |
| `get_status` | Quick overview: active agents, inbox count, recent activity |
### Assets
| Tool | Description |
|------|-------------|
| `list_assets` | List all furniture on the property |
| `add_asset` | Add furniture (optionally with station, tileset, position, `archive: true` for card storage) |
| `remove_asset` | Remove an asset by ID |
| `move_asset` | Move an asset to a new position |
| `attach_content` | Attach a local file's content to an asset |
| `read_asset_content` | Read content attached to an asset (fuzzy name match) |
| `write_content` | Write markdown directly to an asset's content section by name |
| `sync_property` | Refresh local property view from hub |
### Inboxes
| Tool | Description |
|------|-------------|
| `send_message` | Send a message to an inbox. Supports named inboxes (`inbox`, `inbox-bugs`, etc.) |
| `check_inbox` | Read messages from an inbox |
| `clear_inbox` | Clear all messages from an inbox |
### Signals
| Tool | Description |
|------|-------------|
| `subscribe` | Subscribe to a signal on the property (heartbeat or manual) |
| `check_events` | Block until the subscribed signal fires (up to 10 min) |
| `fire_signal` | Fire a signal manually (all subscribers receive it) |
### DTOs (Data Transfer Objects)
| Tool | Description |
|------|-------------|
| `create_dto` | Create a DTO at a station queue with an initial payload. DTOs travel through stations, each stop appending to a trail of results |
| `receive_dto` | Receive DTOs from a station queue. Supports `all` (batch), `headers_only` (compact metadata), and `dto_id` (specific DTO) |
| `forward_dto` | Append your result to a DTO's trail and forward it to the next station. Call `receive_dto` first to get the DTO id |
### Tasks
| Tool | Description |
|------|-------------|
| `read_task` | Read a task station's instructions and current status |
| `work_task` | Block until a visitor triggers a task, then return the instructions. Loop: `work_task` -> do work -> `answer_task` -> `work_task` |
| `answer_task` | Post an HTML result to a task station. After this, call `check_events()` again to keep the loop running |
### Reception
| Tool | Description |
|------|-------------|
| `read_reception` | Read a reception station's private instructions and current Q&A state (pending questions, status) |
| `answer_reception` | Post an HTML answer to a pending reception question. Rendered as rich HTML in the viewer |
## How It Works
```
Your Agent ──► MCP Server ──► Hub (POST /api/state)
│
▼
WebSocket broadcast
│
▼
Viewer (browser)
Character walks to station
```
The agent calls `update_state({ state: "writing_code", detail: "Fixing auth bug" })`. The MCP server posts to the hub. The hub broadcasts to all connected viewers. Your character walks to the desk. You walk to the fridge.
## Multi-Agent
Multiple agents can connect simultaneously — each gets their own character. Set different `AGENT_NAME` and `AGENT_SPRITE` for each:
```json
{
"mcpServers": {
"viz-claude": {
"command": "npx",
"args": ["the-agents-mcp"],
"env": {
"HUB_URL": "http://localhost:4242",
"AGENT_NAME": "Claude",
"AGENT_SPRITE": "Yuki"
}
},
"viz-copilot": {
"command": "npx",
"args": ["the-agents-mcp"],
"env": {
"HUB_URL": "http://localhost:4242",
"AGENT_NAME": "Copilot",
"AGENT_SPRITE": "Kael"
}
}
}
}
```
## I Know You Didn't Read Any of That
Just paste this into Claude:
```
Add the-agents-mcp to my .mcp.json so I can watch you work as a pixel character.
The hub is already running at http://localhost:4242. MAKE NO MISTAKE.
```
## Related
| Package | For | Install |
|---------|-----|---------|
| [The Agents Hub](https://github.com/IronLain88/The-Agents-Hub) | Server | `docker run -p 4242:4242 zer0liquid/the-agents-hub` |
| [the-agents-openclaw](https://github.com/IronLain88/The-Agents-openclaw) | OpenClaw | `openclaw plugins install the-agents-openclaw` |
| [the-agents-vscode](https://github.com/IronLain88/The-Agents-VSCode) | VS Code (viewer only) | Extension install |
## Don't dare to launch a token. THERE IS NONE AND NEVER WILL BE ONE
But i love crypto , so please be a (wo)man of culture and support one of these $y2k,$md,$xavier,$crypto,$spx6900
They contributed here and have an immense talent and I want to honor that
## License
[MIT](./LICENSE)