Skip to content

Serve Commands

Expose SuperQode to other tools: an ACP agent for editors and benchmarks, MCP and A2A servers for harnesses, and a browser-based TUI.

Servers at a glance

Surface Command Who connects
ACP superqode serve acp Any ACP client: Zed, JetBrains IDEs, Neovim, Devin Desktop, and the Harbor benchmark framework. Runs SuperQode as the coding agent, driven by your HarnessSpec.
MCP superqode mcp Any MCP client (Claude Desktop, IDEs, other agents). Exposes your HarnessSpec workflows as list_harnesses, describe_harness, and run_harness tools.
Harness MCP alias superqode serve harness --spec harness.yaml Same MCP server, shaped around one harness file or directory.
Local Session API superqode serve api Browser/mobile companions and local tools that inspect or drive the switchboard and Software Factory graph.
Web TUI superqode serve web A browser, for the full TUI without a terminal emulator.
A2A superqode serve a2a --spec harness.yaml Other agents and orchestrators over A2A 1.0 HTTP+JSON. See A2A Providers.

A2A is the primary cross-service surface. The public Agent Card is published for discovery; operational requests use the interface URL inside the card (temporary public pilot, bearer required). Local serve a2a works today. See A2A Protocol.

mcp

Serve your harness specs over MCP, on stdio by default:

superqode mcp                                  # stdio (for MCP client configs)
superqode mcp --http --host 0.0.0.0 --port 8765
superqode mcp --dir ./harnesses                # serve specs from a directory
Option Description
--http Serve over streamable HTTP instead of stdio
--host Bind address (default: 127.0.0.1)
--port Port number (default: 8765)
--dir Directory of harness specs to expose

A typical MCP client configuration entry:

{
  "mcpServers": {
    "superqode": {
      "command": "superqode",
      "args": ["mcp"]
    }
  }
}

serve acp

Run SuperQode as an ACP agent on stdio, for Zed, JetBrains IDEs, Neovim, and Harbor/Terminal-Bench:

superqode serve acp                       # per-session harness discovery
superqode serve acp --spec harness.yaml   # pin one HarnessSpec
Option Description
--spec HarnessSpec file to use for all sessions
--dir Directory of harness specs for discovery
--provider Provider override (env: SUPERQODE_ACP_PROVIDER)
--model Model override (env: SUPERQODE_ACP_MODEL)

SUPERQODE_ACP_SPEC accepts a spec path or template:<name> for a built-in template. stdout carries JSON-RPC, so human-facing output goes to stderr. See the full guide: ACP Agent Server.

serve harness

Expose harness workflows as MCP tools with a command that reads like harness-as-a-service:

superqode serve harness --spec harness.yaml
superqode serve harness --dir ./harnesses --http --port 8765

--spec serves the containing directory so relative inherits paths keep working; use the file stem as the harness name.

serve api

Serve the local switchboard and Software Factory graph over JSON HTTP.

superqode serve api --port 8766
superqode serve api --host 0.0.0.0 --allow-remote --token "$SUPERQODE_API_TOKEN"

Options:

Option Description
--host Bind address (default: 127.0.0.1)
--port Port number (default: 8766)
--storage-dir Session storage directory (default: .superqode/sessions)
--allow-remote Allow binding outside localhost
--token Optional bearer token

Useful endpoints:

Endpoint Purpose
GET /health Health check
GET /sessions List graph sessions
GET /sessions/graph Session switchboard tree
GET /sessions/{id}/history Recent transcript messages
POST /sessions/{id}/switch Mark a session active
POST /sessions/{id}/handoff Create or deliver a handoff
GET /factory/routes List Software Factory routes
GET /sessions/{id}/factory Factory metadata for a session
POST /sessions/{id}/factory/model Record a model/provider switch
POST /sessions/{id}/factory/harness Record a harness switch
POST /sessions/{id}/factory/mode Set a route such as no-subscription

Remote serving should use --token and a trusted network.

serve web

Start the Textual TUI server over HTTP.

superqode serve web [OPTIONS]

Options

Option Description
--host Bind address (default: 127.0.0.1)
--port Port number (default: 8000)

Examples

superqode serve web
superqode serve web --host 0.0.0.0 --port 8080

Uses textual-serve to expose the full SuperQode TUI over HTTP. Open the provided URL in a browser for a terminal-like experience without a local terminal emulator.

serve a2a

Expose a HarnessSpec as an A2A 1.0 HTTP+JSON agent:

superqode serve a2a --spec harness.yaml
superqode serve a2a \
  --spec harness.yaml \
  --host 0.0.0.0 \
  --allow-remote \
  --public-url https://superqode.example.com \
  --token "$SUPERQODE_A2A_TOKEN"
superqode serve a2a \
  --public-url https://super-agentic.ai/superqode/a2a \
  --token preview-only-value \
  --export-agent-card examples/a2a/agent-card.json
Option Description
--spec HarnessSpec file to serve
--provider / --model Session defaults (env: SUPERQODE_PROVIDER, SUPERQODE_MODEL)
--host / --port Bind address (default 127.0.0.1:8000)
--public-url Interface URL advertised in the Agent Card
--harness-store / --store SQLite harness sessions, runs, evidence
--task-store SQLite A2A task records (survives restart)
--token Bearer token (env: SUPERQODE_A2A_TOKEN; required for remote bind)
--allow-remote Allow binding outside localhost
--export-agent-card Write the runtime Agent Card JSON and exit

See A2A Protocol for durability, publishing, and the experimental multiplayer-computer packaging notes.

serve status

Inspect server integrations supplied by the optional SuperQode Enterprise package.

superqode serve status

The open-source package reports that this surface requires the Enterprise package. The open-source serve acp, serve a2a, serve harness, serve api, and serve web commands remain available as documented above.