MCP tool reference

The riby-mcp server exposes four tools. Three create a request and block until it resolves; one reconciles state after a restart.

Payloads are pager-sized on purpose. The caps below are enforced by the server. Send summaries, not source. Never put secrets in a page.

Shared parameters

Every request tool takes:

Parameter	Required	Cap	Purpose
`title`	yes	200 chars	The one-line question. Shown everywhere.
`gist`	yes	1,500 chars	The context needed to decide: what, why, consequences.
`extended`	no	5,000 chars	Extra detail, viewable on the dashboard only. Chat channels show title and gist.

request_permission

Ask the human to approve or deny an action, then wait for the answer.

Extra parameter:

Parameter	Required	Values
`danger_level`	no	`low`, `medium`, `high`

{
  "title": "Run prisma migrate on prod?",
  "gist": "Adds NOT NULL to users.email. Three existing rows get backfilled first; rollback script is staged.",
  "danger_level": "high"
}

request_plan_check

Ask the human to sign off on a plan before executing it. Same parameters as the shared set: put the plan summary in gist, overflow detail in extended.

{
  "title": "Plan: migrate auth to Clerk",
  "gist": "1. Add Clerk provider. 2. Swap session middleware. 3. Backfill user records. 4. Remove legacy auth. Est. 6 files touched, no schema changes."
}

request_steering

Ask the human to choose a direction. Optionally offer up to 4 options; free text is always possible.

Extra parameter:

Parameter	Required	Cap	Purpose
`options`	no	4 options, labels 200 chars each	Choice buttons. Mark at most one `"recommended": true`.

{
  "title": "Which retry strategy?",
  "gist": "The webhook endpoint flakes under load. Both approaches pass the existing tests.",
  "options": [
    { "label": "Exponential backoff, max 5 retries", "recommended": true },
    { "label": "Dead-letter queue, manual replay" }
  ]
}

Free-text answers are capped at 2,000 characters.

No parameters. Reconciles this instance's local ledger with the server. Call it after a crash or restart to pick up answers that arrived while the agent was down. Returns the instance identity and every reconciled request with its current status.

Results

Request tools resolve when the human answers or the TTL expires. The result includes:

Field	Meaning
`status`	Final request status
`decision`	`approved` or `denied`, where applicable
`answer`	Free-text reply, or `"Denied by timeout"` on expiry
`chosenOption`	The selected steering option, if any
`resolvedVia`	Which channel answered
`expired`, `deniedByTimeout`	`true` when the TTL ran out. Treat as a definitive no.

Waiting behavior

While a request is pending, the server emits an MCP progress notification every 20 seconds. This keepalive is what stops harnesses from timing out or backgrounding the call, so the agent genuinely waits. Requests expire to deny after 6 hours by default; the TTL is adjustable from the dashboard settings.

Instance identity

Each running MCP server instance labels its pages folder · branch (for example riby · main), so five agents on one machine stay distinguishable. Override with the RIBY_SESSION_NAME environment variable, up to 100 characters.