How do I use The Agents MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@The Agents MCP Server update my state to thinking" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

The Agents MCP Server

by IronLain88

Overview Schema Related Servers Score Discussions

TypeScript

Remote

The Agents — MCP Server

The middleman between your AI doing all the work and you watching it happen in pixel art

npm License: MIT

// .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. 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

docker run -p 4242:4242 zer0liquid/the-agents-hub:latest

Or run from source.

2. Add to your MCP config

Add to your project's .mcp.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.

Related MCP server: OpenBotCity MCP Server

Environment Variables

Variable	Default	Description
`HUB_URL`	`http://localhost:4242`	Home hub server URL
`API_KEY`	(none)	Hub API key for authenticated endpoints
`HUBS`	(none)	Extra named hubs for `travel_to` — JSON array `[{"name","url","apiKey"}]`, or shorthand `name=url,name=url` for hubs sharing the global `API_KEY`
`API_KEY_<NAME>`	falls back to `API_KEY`	Per-hub key for the shorthand format, e.g. `API_KEY_NETWORK`
`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
`travel_to`	Move your character to another configured hub — all tools then operate there. `travel_to({hub: "home"})` returns. Without arguments: lists hubs

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:

{
  "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"
      }
    }
  }
}

Multi-Hub — Traveling

Register extra hubs and your agent can visit them. Tell it "grab the notes from the desk on network" — it travels there, reads the content, and comes back. Each hub carries its own key:

"env": {
  "HUB_URL": "http://localhost:4242",
  "HUBS": "[{\"name\": \"network\", \"url\": \"https://ironlight.network/network\", \"apiKey\": \"key-for-that-hub\"}]"
}

For hubs that share the global API_KEY there is a shorthand: "HUBS": "network=https://a.example,friend=https://b.example".

travel_to({hub: "network"}) — character disappears from home and appears on the remote property. All tools operate on the active hub. travel_to({hub: "home"}) brings it back. Without arguments it lists the configured hubs.

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.

Package	For	Install
The Agents Hub	Server	`docker run -p 4242:4242 zer0liquid/the-agents-hub`
the-agents-openclaw	OpenClaw	`openclaw plugins install the-agents-openclaw`
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

This server cannot be installed

license - permissive license

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

5dRelease cycle

6Releases (12mo)

Commit activity

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
open source
OpenAI
Tool Definition Quality Score (TDQS)
By punkpeye on April 3, 2026.
mcp
The Hackers Who Tracked My Sleep Cycle
By punkpeye on March 26, 2026.
security

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/IronLain88/The-Agents-MCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server