MCP

Connect AI agents to a Runyard Hub with the runyard-mcp stdio server and its complete tool surface.

runyard-mcp is a stdio Model Context Protocol server that ships with the Runyard CLI. It runs locally next to your AI client (Claude Code, Claude Desktop, Codex, Cursor, and others), and translates every tool call into an authenticated HTTP request against your Hub. No workflow logic runs in the MCP server itself — it is a thin, faithful client of the HTTP API.

Install and configure

Install the CLI first (it bundles runyard-mcp) and log in — see the CLI guide:

curl -fsSL https://hub.example.com/install.sh | bash
runyard login --url https://hub.example.com

Then let the CLI write your AI client's MCP config:

# Configure Claude Code in the current project (writes .mcp.json)
runyard mcp install

# Or configure a specific client
runyard mcp install --client claude-desktop

# Or auto-detect and configure every AI client found on this machine
runyard mcp install --all

# Claude Code, user-level instead of per-project
runyard mcp install --client claude-code --global

# Bind the server to a specific saved remote (org)
runyard mcp install --remote staging

Supported --client values: claude-code, claude-desktop, codex, cursor, windsurf, gemini, vscode. Each writes the appropriate config file (for example .mcp.json for Claude Code, ~/.codex/config.toml for Codex, .vscode/mcp.json for VS Code) and prints how to activate it.

To configure a client by hand, print the snippet instead:

runyard mcp config     # alias: runyard mcp-config

{
  "mcpServers": {
    "runyard": {
      "command": "node",
      "args": ["/path/to/runyard/src/mcp.js", "--remote", "default"]
    }
  }
}

Hub URL and token resolution

The server name is runyard for the default remote and runyard-<remote> for others, so one client can talk to several Hubs. No token is stored in client configs. At startup the server resolves its target in this order:

RUNYARD_HUB_URL / RUNYARD_HUB_TOKEN environment variables (legacy SMITHERS_HUB_URL / SMITHERS_HUB_TOKEN and HUB_URL / HUB_TOKEN still work)
The --remote <name> argument, resolved against the saved remotes in ~/.runyard/config.json (written by runyard login)
The current saved remote

The token's scopes decide what the tools may do — a token with mcp scope can discover, preflight, and run workflows; admin unlocks the admin tools listed below.

The tool surface

The server exposes tools generated from the same API surface registry the Hub's routes and /openapi.json come from. Curated MCP adapters keep agent-friendly argument names and aliases while deriving HTTP method, path, scope notes, required idempotency keys, and retry headers from src/apiSurface.js. Grouped by resource:

Group	Tools
Discovery & identity	`get_menu`, `whoami`, `get_dashboard`, `list_repo_options`
Workflows	`list_workflows`, `search_workflows`, `describe_workflow`, `get_workflow_source`, `list_workflow_versions`, `create_workflow`†, `update_workflow`†, `delete_workflow`†
Running	`preflight_workflow`, `run_workflow`, `rerun_workflow_run`, `retry_run`, `promote_run`, `cancel_run`
Runs (observe)	`list_runs`, `get_run_status`, `get_run_handoff`, `get_run_events`, `get_run_timeline`, `get_run_diagnostics`, `get_run_logs`
Run drafts	`list_run_drafts`, `get_run_draft`, `create_run_draft`, `update_run_draft`, `submit_run_draft`, `discard_run_draft`
Schedules	`list_schedules`, `get_schedule`, `preview_schedule`, `create_schedule`†, `update_schedule`†, `enable_schedule`†, `disable_schedule`†, `delete_schedule`†, `run_schedule_now`†
Approvals	`list_pending_approvals`, `list_approvals`, `get_approval`, `create_approval`, `approve_run`, `reject_run`, `request_changes_run`
Artifacts	`get_run_artifacts`, `search_artifacts`, `download_artifact`
Runners	`list_runners`
Tokens	`list_tokens`†, `create_token`†, `revoke_token`†
Secrets	`list_secrets`†, `set_secret`†, `delete_secret`† (names and metadata only — values are never readable)
Hooks	`list_hooks`, `get_hook`, `upsert_hook`†, `validate_hook`†
Workflow endpoints	`list_workflow_endpoints`†, `get_workflow_endpoint`†, `upsert_workflow_endpoint`†, `submit_workflow_endpoint`
Workflow bundles	`list_workflow_bundles`, `get_workflow_bundle`, `publish_workflow_bundle`†
Workflow packages	`export_workflow_package`†, `validate_workflow_package`†, `preview_workflow_import`†, `import_workflow_package`†
Catalog	`list_agents`, `list_skills`, `search_knowledge`, `create_agent`†, `update_agent`†, `create_skill`†, `update_skill`†, `create_knowledge`†, `update_knowledge`†
Factory Items	`list_factory_items`, `get_factory_item`, `preview_factory_item_status_move`, `create_factory_item`, `update_factory_item`, `delete_factory_item`†, `link_factory_item_run`, `unlink_factory_item_run`
Boards	`list_boards`, `get_board`, `create_board`, `update_board`, `list_board_definitions`, `get_example_board_definition`, `export_board_definition`, `validate_board_definition`, `import_board_definition`, `describe_board_transitions`, `check_board_transition`
Admin & updates	`get_audit_log`†, `list_alerts`†, `get_update_status`†, `apply_update`†
Assistant	`list_copilot_conversations`, `create_copilot_conversation`, `get_copilot_conversation`, `send_copilot_message`, `confirm_copilot_action`, `archive_copilot_conversation`, `get_assistant_status`, `ask_assistant`

Tools marked † require an admin-scoped token.

Use run_schedule_now when an external cron or agent should appear as Scheduled automation in RunYard. Direct run_workflow calls keep their MCP/token provenance and are not relabeled as scheduled runs.

Mutating tools that can duplicate a dispatch or resolution require idempotencyKey: run_workflow, submit_run_draft, run_schedule_now, link_factory_item_run, unlink_factory_item_run, approve_run, reject_run, and request_changes_run, plus copilot handoff tools send_copilot_message and confirm_copilot_action. Generate one UUID per user intent and reuse it if the MCP client retries the same tool call after a transport failure. Legacy compatibility aliases such as run_capability, describe_capability, and rerun_run are normalized before validation and dispatch. The Hub replays same-key/same-body calls and returns 409 for same-key/different-body calls.

For assistant handoff, prefer the typed copilot conversation flow: create a conversation, send messages with an idempotency key, render only the returned typed actions, and confirm a stored actionId with a second idempotency key. The Hub revalidates scopes and references before execution, stores the outcome, and returns the same outcome on duplicate confirms. ask_assistant is now a deprecated compatibility wrapper over this same typed copilot message path. It creates or reuses a conversation and never exposes the old browser-authored button action contract.

The stdio server validates each tools/call against the advertised tool input schema before it constructs an HTTP URL or request body. Missing required fields, primitive type mismatches, enum mismatches, and invalid object/array shapes return JSON-RPC -32602 invalid params errors and do not contact the Hub. Legacy compatibility aliases documented by the tool surface, such as legacy workflow/capability/id workflow selectors, are normalized before validation. Unknown fields are currently accepted for forward compatibility; agents should not rely on them unless the tool schema documents the field.

Workflow source is always created and edited through these tools — create_workflow / update_workflow take inline source bytes or an existing workflow.bundleId, and import_workflow_package installs a portable package as a disabled workflow. Bare file paths on the runner are rejected.

The parity guarantee

The tool list, the HTTP routes, and /openapi.json are all generated from one registry, and a test fails the build when they drift: every Hub API operation is either exposed as an MCP tool or carries a documented exemption (exempt operations are browser pages, install assets, the runner-to-Hub machine protocol, SSE streams that tools cover by polling, and legacy aliases). If you can do it in the web UI or over HTTP, your agent can do it over MCP.

Recommended agent flow

get_menu — orient: catalog, execution modes, follow-up paths.
preflight_workflow — dry-run your input; resolve needs_input questions and blocked blockers before creating anything (or use run_workflow with negotiate: true, or the run-draft tools for a multi-turn negotiation).
run_workflow — include a short human-readable input.title so run lists and approval cards read well; choose executionMode local or remote.
get_run_timeline — poll with the returned nextSince cursor while the run is active.
get_run_handoff — after the run finishes, pauses, waits for approval, or stops at budget, fetch one bounded handoff pack for final reporting or continuation. It includes next action, approvals, usage/budget, output keys and safe scalar fields, top artifact download links, diagnostics, flow, work-item linkage, and deep links. Use get_run_logs, get_run_diagnostics, get_run_artifacts, and download_artifact only when the handoff points you to deeper detail.

download_artifact is bounded for agent safety. Text artifacts are returned inline only up to RUNYARD_MCP_ARTIFACT_INLINE_BYTE_CAP (default 65536 bytes). Binary artifacts and oversized text return metadata plus the authenticated Hub download URL instead of base64/content. Legacy consumers can request inlineBinary: true for small binary artifacts, but the same byte cap still applies.

If a run pauses for a human, list_pending_approvals shows the card and approve_run / reject_run / request_changes_run resolve it (by approvalId, not runId).

Retired names

The Factory Item tools were called *_work_item before the Work → Factory rename, and the CLI commands were runyard work and runyard work-item. Every retired name is still accepted and resolves to its canonical replacement, so existing MCP clients, scripts, saved prompts and agent memories keep working. Only the canonical names are advertised.