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

Embedded workflows mode (o8e1 embed tokens)

Vendors that embed Orch8 in their product can give each end customer an AI assistant that sees only that customer's workflows. embed/ is a dependency-free MCP server (Node 18+) authenticated by an o8e1 embed token (issued by the vendor backend with POST /api/v1/embed/tokens, max TTL 1 h). It talks to the engine's sub-tenant-scoped /api/v1/embed/* routes only, and never holds or accepts a tenant API key.

Tenant-level tools (list_sequences, create_instance, send_signal, get_usage, ...) do not exist in this mode; calling one is an unknown-tool error. The token's seq list decides which start_ tools appear (seq: null lists the sub-tenant's sequences through GET /embed/sequences). The server only decodes the token to build the catalog; the engine verifies signature, expiry, sub-tenant and allow-list on every call.

# stdio, one end user (Claude Desktop, Cursor, ...)
ORCH8_URL=https://orch8.example.com ORCH8_EMBED_TOKEN=o8e1... node embed/bin.mjs
# ORCH8_EMBED_TOKEN_FILE=/path/to/token is re-read on every request, so a refreshed token takes effect

# Streamable HTTP, many end users: each request sends its own Authorization: Bearer o8e1...
ORCH8_URL=https://orch8.example.com node embed/bin.mjs --http --port 8787 --host 127.0.0.1

The HTTP endpoint (POST /mcp) answers 401 to requests without an o8e1 bearer token, including x-api-key tenant credentials. Tests: embed/embed.test.mjs (part of npm test / pnpm test).

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.