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

1. Sign up free at pixelagents.squads.digital
2. Create a room
3. Go to the Conectar tab
4. 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