Orch8 MCP distribution

Orch8 engines expose a Model Context Protocol server over Streamable HTTP at POST {ORCH8_URL}/api/v1/mcp (the bare /mcp alias also works). It uses the same x-api-key / x-tenant-id headers and tenant boundary as the REST API and offers these tools: list_sequences, create_sequence, preflight_sequence, lint_sequence, create_instance, get_instance_status, get_instance_outputs, send_signal, retry_instance, list_dlq, get_usage. Negotiated protocol versions: 2024-11-05, 2025-03-26, 2025-06-18. JSON-RPC batches are not supported; responses are plain JSON (no SSE stream).

Orch8 is self-hosted, so there is no single public URL: every snippet below uses http://localhost:8080 — replace it with your engine's address.

Quick start (works today, no registry needed)

Point your client straight at your own engine. Examples with https://orch8.example.com:

# Claude Code
claude mcp add --transport http --scope user orch8 https://orch8.example.com/api/v1/mcp \
  --header "x-api-key: $ORCH8_API_KEY" --header "x-tenant-id: $ORCH8_TENANT_ID"

// Cursor: ~/.cursor/mcp.json
{
  "mcpServers": {
    "orch8": {
      "url": "https://orch8.example.com/api/v1/mcp",
      "headers": { "x-api-key": "${env:ORCH8_API_KEY}", "x-tenant-id": "${env:ORCH8_TENANT_ID}" }
    }
  }
}

The other clients are in clients/ (also zipped as orch8-mcp-clients-<tag>.zip on each GitHub Release); change the URL in them the same way. For Claude Code you can instead install the plugin: claude plugin marketplace add orch8-io/claude-code-plugin then claude plugin install orch8@orch8.

Do not commit literal API keys. Prefer a tenant key with the least capability that works (operator for authoring/running, approver only answers human gates).

Related MCP server: n8n Architect MCP Server

Checking the files

npm install
npm test   # validates server.json against the vendored 2025-12-11 registry schema + lints client snippets

The schema is vendored under schema/ from https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json.

Smoke-testing an engine

curl -s -X POST "$ORCH8_URL/api/v1/mcp" \
  -H "content-type: application/json" \
  -H "x-api-key: $ORCH8_API_KEY" -H "x-tenant-id: $ORCH8_TENANT_ID" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

CI and releases

• .github/workflows/ci.yml runs npm test (schema validation of server.json and client snippet lint) and checks the vendored schema still matches the $schema URL, on every push and PR to main.

• Pushing a tag v* runs .github/workflows/release.yml: tests, then a GitHub Release with server.json and the client-config zip.

• The same workflow publishes to the official MCP Registry with mcp-publisher (pinned v1.8.1, sha256-checked) only if the repository secret MCP_PRIVATE_KEY is set. It runs mcp-publisher login dns --domain orch8.io --private-key "$MCP_PRIVATE_KEY", then mcp-publisher publish. The published version is server.json's version, not the git tag; registry versions are immutable, so bump it before each publish.

One-time setup for registry publishing (DNS auth for the io.orch8/* namespace), using OpenSSL 3 (on macOS: /opt/homebrew/opt/openssl@3/bin/openssl, since LibreSSL has no Ed25519):

openssl genpkey -algorithm Ed25519 -out key.pem
# 1. TXT record on the apex of orch8.io (not a subdomain):
echo "orch8.io. IN TXT \"v=MCPv1; k=ed25519; p=$(openssl pkey -in key.pem -pubout -outform DER | tail -c 32 | base64)\""
# 2. The hex private key goes into the MCP_PRIVATE_KEY repository secret (prefer an environment secret):
openssl pkey -in key.pem -noout -text | grep -A3 "priv:" | tail -n +2 | tr -d ' :\n'

Then keep key.pem offline or delete it. See https://github.com/modelcontextprotocol/registry/blob/main/docs/modelcontextprotocol-io/authentication.mdx.

Submission steps for the registry and every client directory are in SUBMISSION.md.