Connect an MCP agent

Audience: people connecting Claude Code or another MCP client to Spiron.

Spiron's MCP endpoint exposes its existing hosted agents. Connecting a client lets that client list agents, send a real task, read the result and cancel it. It does not enroll the local session as an external Outcome owner. That registration and delivery contract is not implemented yet; the destination is ADR 0015. There is no local job runner or claim loop.

Connect with one command

Prerequisites: macOS or Linux, curl, Node.js 22 or later, and Claude Code on PATH. Sign in to your own Spiron workspace when the approval page opens.

curl -fsSL https://spiron.ai/connect.sh | sh

The command installs the MCP connector under ~/.local/share/spiron/connect/, starts device authorization and displays the approval URL and user code. A workspace owner or admin approves the requested read/write access on spiron.ai/device. The approved workspace determines access; no workspace id, API key or platform configuration needs to be copied.

Expected output after approval:

Connected to Spiron. Claude Code MCP server: spiron
Restart Claude Code, then ask it to list your Spiron agents.

The connector registers a user-scoped stdio server using claude mcp add. Its registration contains only a local command and credential-file path, not an Authorization header or a token. Credentials are stored in ~/.config/spiron/connect/credentials.json with mode 0600. Access tokens expire after one hour. The connector serializes refresh across local sessions, keeps each rotated refresh token and supplies the current access token on each HTTP request. A failed or revoked refresh asks you to reconnect; it never substitutes a permanent key.

Other MCP clients

Install and sign in without changing Claude Code's configuration:

curl -fsSL https://spiron.ai/connect.sh | sh -s -- --client generic

The command prints a standard mcpServers JSON entry. Add it through your client's normal configuration interface. It invokes the same connector's serve command and uses the same refreshable credential file.

Give an agent real work

After restarting the MCP client:

1. Ask it to call list_agents. The result lists only agents in the approved workspace. An empty list means the connection worked but that workspace has no agents yet.
2. Pick an existing agent and ask message_agent to carry out a real task you are authorized to request. Its result is a reply or a task id. Preserve the task id and use get_task for its state and result.
3. To stop that task, call cancel_task with its task id. To disconnect the local transport, stop your MCP client; the connector exits on stdin EOF. Stopping the client does not cancel an already submitted hosted task.

Spiron owns the task-handoff deadline: message_agent waits at most sixty seconds before returning a result or a task id. wait_seconds may shorten that wait, but cannot extend it. The connector allows ninety seconds for an MCP HTTP request: that server wait plus thirty seconds for request and response overhead. Device authorization and refresh HTTP calls keep their thirty-second limit. A slow task can therefore return its task id without the connector ending the request first.

These are the existing Agents API tools, not a local worker definition. The client does not select labels, claim Outcomes, start another agent runtime, clone repositories or publish pull requests on your behalf.

Disconnect and recover

Remove Claude Code's registration with claude mcp remove --scope user spiron. Revoke the connection's Spiron MCP (device) entry in Spiron Settings to end both access and refresh. Removing local configuration alone is not revocation.

An approval denied or expired creates no registration. Run the install command again to reconnect. If claude is not on PATH, use --client generic, or install Claude Code first. An HTTP or refresh error is reported without tokens; reconnect after restoring access. Reconnecting replaces the local credential file, while old connections remain revocable through Settings.