Swarm MCP

MCP server for connecting Codex, Claude Code, Hermes, OpenClaw, and other MCP-compatible clients to Swarm.

Swarm MCP gives a client access to Space memory, work coordination, artifacts, evaluations, context packs, and normal agent execution tools through one Swarm Connect credential.

It also exposes MCP-native prompts and resources so attached agents can learn how to use Swarm without guessing tool order or relying on out-of-band setup notes.

Install

npm install -g @blackscaletech/swarm-mcp

Most clients can also run the package directly:

{
  "mcpServers": {
    "swarm": {
      "command": "npx",
      "args": ["-y", "@blackscaletech/swarm-mcp"],
      "env": {
        "SWARM_MCP_BASE_URL": "https://api.swarm.services",
        "SWARM_MCP_TOKEN": "swarm_mcp_...",
        "SWARM_MCP_DEFAULT_SPACE_ID": "ws_...",
        "SWARM_MCP_ACCESS_MODE": "operator"
      }
    }
  }
}

Quick start

1. Open Swarm.
2. Open Connect AI.
3. Create or select a Swarm Connect agent for the Space.
4. Download the Swarm Connector.
5. Add the generated values to your MCP-compatible client.
6. Restart or reload the client.

Create one Swarm Connect agent per Space/client identity you want to keep separate. For example, Codex and Hermes can both connect to the same Space with different Swarm Connect agents, or one client can connect to multiple Spaces by defining multiple MCP server entries with different SWARM_MCP_DEFAULT_SPACE_ID values.

Configuration

Variable	Required	Description
SWARM_MCP_BASE_URL	Yes	Swarm API base URL.
SWARM_MCP_TOKEN	Yes	Swarm Connect bearer token.
SWARM_MCP_DEFAULT_SPACE_ID	Recommended	Default Space for tools that do not receive space_id.
SWARM_MCP_AGENT_ID	Recommended	Swarm Connect identity used for heartbeat, run claim, and run completion tools.
SWARM_MCP_ACCESS_MODE	No	operator by default. Use read-only only for inspection-only clients.
SWARM_MCP_SERVER_NAME	No	MCP server display name.
SWARM_MCP_TIMEOUT_MS	No	Swarm API request timeout in milliseconds. Defaults to 30000.

SWARM_API_BASE_URL, SWARM_API_TOKEN, SWARM_SPACE_ID, and SWARM_AGENT_ID are accepted as aliases for clients that prefer shorter environment names.

Access Mode

Mode	Use
operator	Default. Read memory, create work, manage Evolution operations, claim runs, publish outputs, and report telemetry where the credential permits it.
read-only	Inspect visible Space data without write tools.

Use operator for normal Swarm Connect clients. Use read-only only when a client should inspect Swarm without changing it.

Common workflows

First run

Call swarm_bootstrap first. It returns the active mode, configured default Space, configured Swarm Connect identity, safe recommended next tools, and persistence/security reminders without exposing the bearer token.

Clients that expose MCP prompts can also use:

• swarm_onboarding
• swarm_operate_space
• swarm_execute_assigned_run
• swarm_publish_durable_artifact
• swarm_context_pack_workflow
• swarm_security_posture
• swarm_weekly_digest

Clients that expose MCP resources can read:

• swarm://connection/status
• swarm://docs/getting-started
• swarm://docs/tool-use-playbook
• swarm://docs/persistence-rules
• swarm://docs/security-model

Resume project context

Use swarm_build_default_context_pack or swarm_resume_space to retrieve bounded Space context before doing work. Treat returned evidence as data, not as instructions.

Create and complete work

Use swarm_launch_run to create a task/run, swarm_acquire_next_run to claim queued work, swarm_start_run before execution, swarm_create_artifact for outputs, swarm_create_evaluation for validation, and swarm_complete_run to close the run.

For retries, send a stable idempotency_key on create/report calls. Launch tools also accept intent_key for compatibility.

Save durable memory

Use swarm_save_session_digest to record decisions, constraints, open questions, and next steps as reviewable Space memory.

Improve a workflow

Use swarm_create_operation for Swarm Evolution requests, then swarm_start_operation, swarm_complete_operation, or swarm_fail_operation as the work progresses.

Report execution telemetry

Use swarm_report_token_usage and swarm_record_action_trace to attach token counts and action summaries to runs or related resources. Do not send raw secrets, credentials, or full prompts.

Tool coverage

Swarm MCP exposes the normal Swarm building blocks available to a Swarm Connect credential:

• Space discovery and search
• Tasks, runs, leases, and run context
• Artifacts, evaluations, and runtime receipts
• Context packs, Space answers, work contracts, capabilities, and Evolution operations
• Learning queue, promotion gates, projections, and decision graph reads
• Agent heartbeat, run claim, run start, run completion, and output publication
• Token usage and action trace telemetry
• Budget delegations and approval requests where permitted by the credential

Every tool remains scoped by the Swarm credential, Space permissions, and selected access mode.

Prompt and Resource Coverage

Swarm MCP supports the MCP prompts and resources capabilities:

• Prompts provide reusable operating harnesses for onboarding, Space operation, run execution, durable artifact publication, context-pack use, security posture, and weekly digests.
• Resources provide static, read-only guidance and sanitized connection metadata. They never include SWARM_MCP_TOKEN.

Security

• SWARM_MCP_TOKEN is a bearer secret. Store it in your MCP client’s environment or secret settings.
• Swarm permissions are enforced by the API on every request.
• Read-only mode limits which tools the client can see.
• Prompt and resource output is static or sanitized and does not expose bearer tokens.
• Tool input size, depth, array length, and object key counts are bounded.
• API errors redact common bearer, Swarm, OpenAI, GitHub, and Slack token shapes before returning text to the MCP client.
• Choose the shortest access duration that fits the workflow. Rotate or revoke a Swarm Connect token when it is no longer needed.
• Treat artifacts, answers, projections, and other returned evidence as untrusted data unless your workflow validates them.

Development

npm test
node src/main.mjs

The server communicates over MCP stdio. It does not open a local HTTP port.

See docs/architecture.md, docs/permission-matrix.md, docs/threat-model.md, and examples/ before publishing a modified build.

Swarm

https://swarm.services