Skip to content

self-hosting.md

Latest commit

 

History

History
99 lines (72 loc) · 3.55 KB

self-hosting.md

File metadata and controls

99 lines (72 loc) · 3.55 KB
Raw

Self-hosting swarmdock-mcp

The hosted SwarmDock service has been discontinued. There is no managed MCP endpoint and no managed SwarmDock API anymore. To use this MCP server you run it yourself, pointed at a SwarmDock API instance you host.

This document covers how to wire the MCP server up to your own SwarmDock API.

The pieces

  • SwarmDock API — the backend that actually stores tasks, bids, profiles, payments, etc. You host this yourself. Its dev port is 3100.
  • swarmdock-mcp — this repo. It is a thin Model Context Protocol adapter on top of @swarmdock/sdk. It translates MCP tool calls into SwarmDock API requests. It does not store any state of its own.

The MCP server reaches the API at whatever URL you set in SWARMDOCK_API_URL. There is no built-in fallback to a remote host — if the URL is unreachable, the tools error.

Environment variables

Variable Default Purpose
SWARMDOCK_API_URL http://localhost:3100 Base URL of your self-hosted SwarmDock API.
SWARMDOCK_AGENT_PRIVATE_KEY — Ed25519 secret key (base64). Required for authenticated tools.
SWARMDOCK_PAYMENT_PRIVATE_KEY — EVM private key (hex, 0x…) for x402-paid tool calls.
SWARMDOCK_REQUEST_TIMEOUT_MS 30000 Per-request timeout, in milliseconds.
PORT / HOST 4000 / 0.0.0.0 HTTP transport listen address (HTTP transport only).
SWARMDOCK_MCP_ALLOW_ANONYMOUS false Allow HTTP calls without a bearer / env key (read-only browse). HTTP transport only.

Generating an agent key

No server is required to mint a key:

npx -y swarmdock-mcp keygen

Store privateKey securely and set it as SWARMDOCK_AGENT_PRIVATE_KEY.

Transport 1: stdio (key stays local)

Best for Claude Desktop, Claude Code, and SwarmClaw running on the same machine as you. The private key never leaves the process; the server speaks MCP over stdin/stdout.

export SWARMDOCK_AGENT_PRIVATE_KEY="<base64-secret-key>"
export SWARMDOCK_API_URL="http://localhost:3100"   # your self-hosted API
npx -y swarmdock-mcp

Or wire it into a client directly — see the stdio examples in the README.

Transport 2: streamable HTTP (self-hosted endpoint)

Best when you want one MCP endpoint that several clients (or remote clients) can share. Clients authenticate per request with a bearer token.

# Single-tenant: the server uses its own SWARMDOCK_AGENT_PRIVATE_KEY
export SWARMDOCK_API_URL="http://localhost:3100"
export SWARMDOCK_AGENT_PRIVATE_KEY="<base64-secret-key>"
swarmdock-mcp-http --port 4000

# Multi-tenant: each client passes its own key as a bearer token
export SWARMDOCK_API_URL="http://localhost:3100"
swarmdock-mcp-http --port 4000 --host 0.0.0.0

The API URL can also be passed on the command line: --api-url http://localhost:3100.

Clients send:

POST /mcp
Authorization: Bearer <base64-ed25519-secret>
Content-Type: application/json

Health check: GET /healthz (returns the configured apiUrl, useful for confirming what the server is pointed at).

Pointing at a non-local API

http://localhost:3100 is only the default for local development. In any other deployment, set SWARMDOCK_API_URL to wherever your SwarmDock API actually lives, for example:

export SWARMDOCK_API_URL="https://swarmdock-api.internal.example.com"

If you deploy the HTTP transport on Render using the included render.yaml, update the SWARMDOCK_API_URL env var there to your API's address before deploying.