mcp

Manage the MCP server registry and audit what a workflow grants. Nodes reach MCP servers by name; this command owns the other half of that reference — the connection definition and its auth — and can tell you, before a run, whether the servers a recipe grants will actually resolve.

The registry is metadata-only: it holds ${NAME} references, never values. A secret enters through a hidden prompt or standard input and lands in the owner-only store, so the registry file stays committable.

Usage

mini-ork mcp list [--json]
mini-ork mcp add <name> (--url <url> | --command <cmd>) [options]
mini-ork mcp rm <name>
mini-ork mcp check [--workflow <workflow.yaml>]
mini-ork mcp launch <name>
mini-ork mcp proxy <name>

Where the registry lives

Registry files are read in this order:

1. <run_dir>/config/mcp_servers.json — a run's own frozen snapshot
2. $MINI_ORK_HOME/config/mcp_servers.json — the only file add/rm write
3. <root>/.claude/mcp_servers.json — repo template
4. <root>/mcp/steering.json — bundled steering servers

The run snapshot wins so a live run cannot be changed by editing a shared file mid-flight. Repo files are committed templates; the home file is yours.

list

Prints every registered server with its transport and whether its ${NAME} references currently resolve. --json emits the same rows as machine input.

add

mini-ork mcp add arxiv \
  --url https://mcp.example.com/arxiv \
  --header 'Authorization=Bearer ${ARXIV_TOKEN}' \
  --secret ARXIV_TOKEN

Flag	Meaning
--url <url>	HTTP or SSE server. Exactly one of --url / --command is required
--command <cmd>	stdio server executable
--header K=V	Repeatable HTTP header; use ${NAME} for auth
--arg V	Repeatable stdio argument
--env K=V	Repeatable stdio environment variable
--secret NAME	Prompt for NAME and store it owner-only (0600)
--replace	Overwrite an existing entry of the same name

--secret skips a name already present in the environment or the secret store and reports that it was left unchanged. It refuses when no hidden prompt is available — export the variable or use mini-ork providers configure instead.

Omitting --replace on an existing name is an error, so a typo cannot silently replace a working server.

check

mini-ork mcp check --workflow recipes/code-fix/workflow.yaml

Resolves every MCP grant a workflow declares — both the tools.mcp block and the mcp_servers envelope — and reports the ones that would fail at dispatch: an unset ${NAME}, a disabled entry, or a server no registry defines. The output names the file add would write. Run this in CI after changing a workflow; it catches a broken grant before any model is billed.

launch and proxy

mini-ork mcp launch <name>   # stdio
mini-ork mcp proxy <name>    # URL server, bridged over stdio

launch is not usually typed by a human: mini-ork zed setup writes it into Zed's settings.json in place of the server itself. Zed spawns launch, which resolves the entry against the vault and execs the real server — so settings.json names a server but never holds its token. proxy does the same for a URL server, bridging it to a stdio client.

Grants in a workflow

A node opts in to servers explicitly:

nodes:
  - name: implement
    tools:
      mcp: [arxiv]          # or: mcp_servers: [arxiv]

A server not granted to a node is not reachable from it, even if the registry defines it. At dispatch, mini-ork passes --strict-mcp-config so a subprocess cannot fall back to a user-level MCP config the workflow did not declare.

Failure behaviour

Situation	Result
Unset ${NAME} in a header/env grant	Hard error at dispatch; never an empty value
Granted server missing from every registry	Hard error naming the node and server
add without --replace on an existing name	Error; the entry is untouched
--url and --command both given	Error; exactly one transport

Examples

mini-ork mcp list --json | jq '.[].name'
mini-ork mcp add filesystem --command npx \
  --arg -y --arg @modelcontextprotocol/server-filesystem --arg "$PWD"
mini-ork mcp check --workflow recipes/framework-edit/workflow.yaml
mini-ork mcp rm filesystem

Related

• mcp-context — the read-only state server agents call
• zed — writes launch entries into editor settings
• vault — where ${NAME} resolves
• Workflow schema — tools.mcp grants