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:

Agent	Command	What it does
Claude Code	superpos-mcp install claude	claude mcp add --scope user superpos -- superpos-mcp serve
Codex CLI	superpos-mcp install codex	codex mcp add (or appends to ~/.codex/config.toml)
Cursor	superpos-mcp install cursor	merges into ~/.cursor/mcp.json
Gemini CLI	superpos-mcp install gemini	merges into ~/.gemini/settings.json
Windsurf	superpos-mcp install windsurf	merges into ~/.codeium/windsurf/mcp_config.json
Anything else	superpos-mcp install print	prints a generic mcpServers JSON snippet

Configuration

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

Variable	Meaning
SUPERPOS_BASE_URL	API base URL (default https://api.superpos.ai)
SUPERPOS_TOKEN	Agent access token
SUPERPOS_AGENT_REFRESH_TOKEN	Refresh token (auto-rotated on 401)
SUPERPOS_HIVE_ID	Default hive for all tools
SUPERPOS_AGENT_ID / SUPERPOS_AGENT_SECRET	Enables automatic re-login when tokens expire

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

Group	Tools
Identity	superpos_whoami, superpos_heartbeat
Tasks	superpos_create_task, superpos_poll_tasks, superpos_claim_task, superpos_get_task, superpos_task_progress, superpos_complete_task, superpos_fail_task
Events	superpos_publish_event, superpos_poll_events
Knowledge	superpos_search_knowledge, superpos_list_knowledge, superpos_get_knowledge, superpos_create_knowledge, superpos_update_knowledge
Schedules	superpos_list_schedules, superpos_create_schedule, superpos_delete_schedule
Issues	superpos_list_issues, superpos_get_issue, superpos_create_issue, superpos_update_issue, superpos_transition_issue, superpos_close_issue, superpos_list_issue_types, superpos_link_task_to_issue, superpos_request_issue_approval, superpos_add_issue_dependency, superpos_remove_issue_dependency
Tracks	superpos_list_tracks, superpos_get_track, superpos_create_track, superpos_update_track, superpos_transition_track, superpos_link_issue, superpos_unlink_issue
Topology	superpos_hive_map
Discovery	superpos_list_hives, superpos_hive_agents
Persona	superpos_get_persona, superpos_update_memory

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.