Superpos

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 (from GitHub until it's published to PyPI)
uv tool install git+https://github.com/Superpos-AI/superpos-mcp.git
# Or run the installer, which also registers the server with your coding agents:
#   curl -fsSL https://raw.githubusercontent.com/Superpos-AI/superpos-mcp/main/install.sh | bash

# 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:

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.

Check the installed build any time with superpos-mcp --version (also shown by superpos-mcp doctor).

Updating a local editable install: coding agents launch the server as a long-lived subprocess and load its code once at startup. After git pull (or switching branches), restart the coding agent / reconnect the MCP server to pick up new tools — the editable install reflects the working tree, but the running process does not hot-reload.

Releasing

The version lives in one place — src/superpos_mcp/__init__.py (pyproject.toml reads it via [tool.hatch.version]). To cut a release:

1. Bump __version__ in src/superpos_mcp/__init__.py.
2. Commit and merge to main.
3. Tag and push: git tag v0.2.0 && git push origin v0.2.0.

The release.yml workflow builds the sdist + wheel, guards that the tag matches __version__, and publishes to PyPI via Trusted Publishing (OIDC — no token secret). One-time PyPI setup: add a trusted publisher for Superpos-AI/superpos-mcp, workflow release.yml, environment pypi. Once published, installs can switch to uv tool install superpos-mcp.

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.