pixelsquads-mcp-server

pixelsquads-mcp-server

MCP Server for Pixel Squads — observe your AI agents working in a pixel-art office, directly from Claude.

What it does

Connect Claude Desktop or Claude Code to your Pixel Squads office. Once connected, Claude can:

• 📊 Check office status — active agents, events/min, errors
• 🚨 View alerts — see firing alerts and their rules
• ⏪ Replay activity — get recent event history
• 👋 Announce yourself — appear as a character in the office
• 📡 Send events — report tool usage to the office in real-time
• 🔗 Show connection info — API endpoint, token status, office URL

Quick start

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "pixel-squads": {
      "command": "npx",
      "args": ["-y", "pixelsquads-mcp-server"],
      "env": {
        "PIXEL_SQUADS_TOKEN": "pa_your_token_here"
      }
    }
  }
}

Claude Code

claude mcp add pixel-squads \
  -e PIXEL_SQUADS_TOKEN=pa_your_token_here \
  -- npx -y pixelsquads-mcp-server

Get your token

• Sign up free at pixelagents.squads.digital
• Create a room
• Go to the Conectar tab
• Copy your API token (pa_xxx...)

Tools

Tool	Description
pixel_squads_office_status	Current office metrics (agents, events/min, errors, alerts)
pixel_squads_alerts	Active alert rules and firing status
pixel_squads_replay	Recent event history (configurable time window)
pixel_squads_announce	Register yourself as an agent in the office
pixel_squads_send_event	Send AEP events (tool.start, tool.done, status, message, handoff)
pixel_squads_connect_info	Show connection details and office URL

Example conversation

You: Check my office status

Claude: calls pixel_squads_office_status

Your Pixel Squads office has 3 active agents with 12 events/minute. No alerts firing. The top tool being used is "Read" with 45 calls in the last hour.

You: Announce yourself in my office

Claude: calls pixel_squads_announce with name="Claude Assistant"

Done! I'm now visible in your office as "Claude Assistant". Open https://pixelagents.squads.digital/agents/?room=... to see me.

Environment variables

Variable	Required	Default	Description
PIXEL_SQUADS_TOKEN	Yes	—	Your AEP token (pa_xxx) from the Conectar tab
PIXEL_SQUADS_URL	No	https://pixelagents.squads.digital	API base URL (for self-hosted)

How it works

Claude Desktop / claude.ai
    │ (MCP protocol via stdio)
    ▼
pixelsquads-mcp-server
    │ (HTTPS + Bearer token)
    ▼
pixelagents.squads.digital/api/v1/*
    │
    ▼
Your pixel-art office 🏢

The MCP server is a thin translation layer. It speaks MCP to Claude and AEP (Agent Event Protocol) to the Pixel Squads backend. Your token scopes all operations to your room — complete isolation.

Development

git clone https://github.com/aitor-alt/pixel.git
cd mcp-server
npm install
PIXEL_SQUADS_TOKEN=pa_xxx npm run dev

License

MIT — Pixel Squads by SquadsLab