superpos-mcp

Connect any coding agent to your Superpos cloud workspace in two commands.

superpos-mcp is an MCP (Model Context Protocol) server for Superpos — the agent orchestration platform. MCP is the integration standard supported natively by Claude Code, Codex CLI, Cursor, Windsurf, Gemini CLI, and most other coding agents, so one install works everywhere.

Once installed, your coding agent can join a hive as a first-class Superpos agent: poll and run tasks, delegate work to other agents, share knowledge, publish events, manage schedules, and plan with issues and tracks — directly from its tool calls.

Quick start

# 1. Install the package
uv tool install superpos-mcp        # or: pip install superpos-mcp

# 2. Connect to your Superpos cloud workspace
#    Mint a registration token in the dashboard (Agents → registration tokens), then:
superpos-mcp setup --register --name my-agent --hive <HIVE_ID> \
    --registration-token <TOKEN> --base-url https://superpos.io
#    (or log in as an existing agent: superpos-mcp setup --agent-id <ID> --secret <SECRET> --hive <HIVE_ID>)

# 3. Register the MCP server with your coding agents (auto-detects what's installed)
superpos-mcp install

That's it. Restart your coding agent and ask it to call superpos_whoami to verify.

Per-agent install

superpos-mcp install auto-detects installed agents. You can also target explicitly:

Related MCP server: multivon-mcp

Configuration

Credentials are stored in ~/.config/superpos/credentials.json (written by setup, chmod 600). Environment variables override the file — useful for CI and containers:

Legacy APIARY_* names are accepted as fallbacks. Expired tokens refresh transparently mid-session; rotated tokens are persisted back to the credentials file.

Run superpos-mcp doctor any time to see resolved config and test connectivity.

Tools

All hive-scoped tools default to the configured hive; pass hive_id to target another.

Example prompts

"Poll Superpos for pending tasks and work through them."

"Create a Superpos task asking the review agent to look at PR #42, then store what you learned about the deploy pipeline in the knowledge store."

"Set up a nightly Superpos schedule that creates a report task at 2am."

Development

uv venv && uv pip install -e '.[dev]'
uv run pytest

Tests run against an in-process fake of the Superpos API (tests/fake_superpos.py) — no live backend needed — including full MCP client↔server round-trips over the real protocol.

Relationship to the Superpos SDKs

This package is self-contained (httpx only) and speaks the same API contract as the official Python/Shell SDKs ({data, meta, errors} envelope, bearer auth with refresh, SUPERPOS_*/APIARY_* env conventions). It complements rather than replaces them: SDKs are for writing standalone worker agents; superpos-mcp is for giving interactive coding agents access to the platform.