MCP server

Hyphen exposes governed operations to external AI clients through MCP. External agents can request and inspect Hyphen runs, while Hyphen enforces the workflow, policy, approval, state, evidence, and trace boundary.

An assistant such as Claude Desktop picks a vetted case from the Process Studio catalog, starts it, reads the record, and hands decisions to people. It cannot declare tools, run queries against your database, read secrets, or reach the engine. Every call goes through the gateway under a publishable key or a signed-in session, with the same scope, rate limits, and audit as the SDK.

What runs today

hyphen-mcp is a server over stdio for local and desktop clients. It calls only /sdk/* and /process-studio/* on your gateway.

bash
HYPHEN_GATEWAY_URL=https://<gateway> \
HYPHEN_PUBLISHABLE_KEY=pk_live_… \
HYPHEN_ORIGIN=https://<an-allowed-origin> \
npx hyphen-mcp
Variable Meaning
HYPHEN_GATEWAY_URL The gateway origin
HYPHEN_PUBLISHABLE_KEY Mints an anonymous SDK session. Caller class: delegated agent
HYPHEN_SESSION_TOKEN A one-time-code-verified SDK session token (skt_…). Caller class: human interactive. Required to decide an approval or settle a paused form
HYPHEN_ORIGIN An origin listed in the publishable key's allowed origins. Publishable keys are origin-bound and a server has no browser origin, so add a dedicated origin to the key for this server

Claude Desktop, in claude_desktop_config.json:

json
{
  "mcpServers": {
    "hyphen": {
      "command": "npx",
      "args": ["hyphen-mcp"],
      "env": {
        "HYPHEN_GATEWAY_URL": "https://<gateway>",
        "HYPHEN_PUBLISHABLE_KEY": "pk_live_…",
        "HYPHEN_ORIGIN": "https://<an-allowed-origin>"
      }
    }
  }
}

Tools

Tool Does Notes
hyphen.list_capabilities Says which caller class this is and what it cannot do
hyphen.list_playbooks Lists the catalog Safe metadata only
hyphen.get_playbook Reads one case: inputs, approval behavior, version
hyphen.start_workflow_run Starts a workflow the key allows idempotency_key required
hyphen.start_agent_run Starts a catalog case as a recipe: apply, publish, execute A recipe that needs a connection is refused; connections are never made here
hyphen.get_run_status, get_run_result, get_run_trace_summary Reads a run or an agent run Minimized and redacted upstream
hyphen.submit_approval Decides an approval task Human interactive only
hyphen.cancel_run Cancels a run
hyphen.query_custom_table Reads rows from an allowed table Default limit 50, maximum 200
hyphen.create_form_from_intent Builds a form from a sentence Returns the hosted URL when created; needs the agent_forms feature
hyphen.get_form, hyphen.submit_form Reads and submits forms Settling a paused step is human only

Two caller classes decide what a tool may do. A delegated agent holds a publishable key: it can start vetted cases and read. A human interactive caller holds a signed-in session: only it can approve, reject, or settle a paused form. The boundary is enforced by the gateway, not by the assistant.

Reuse the same idempotency key when retrying a run start so the client receives the same run handle.