MCP server

The MCP server exposes Reqbook operations as structured JSON-RPC tools for MCP-compatible coding agents. Execution tools return compact JSON by default, rqb_diagnose returns an agent-facing next-action plan after a failed endpoint, and rqb_context returns surgical contract context unless you request compact or schema mode. Full request/response payloads only appear when you pass verbose: true.

Register with an agent

Install a project or agent config

rqb install mcp --agent=claude-code
rqb install mcp --agent=codex-cli
rqb install mcp --agent=cursor
rqb install mcp --agent=copilot
rqb install mcp --agent=opencode

Omit --agent to install MCP config for every detected agent in the workspace.

Restart or reload the agent

Each client discovers MCP servers differently. Restart the agent, reload MCP tools, or use the client’s MCP list command.

Verify registration

claude mcp list
codex mcp list
opencode mcp list

Expected Claude Code output:

rqb: rqb mcp - ✓ Connected

Config files written

Agent	Config file	Shape
Claude Code	`.mcp.json`	`mcpServers.rqb.command = "rqb"`
Codex CLI / IDE	`.codex/config.toml`	`[mcp_servers.rqb]`
Cursor	`.cursor/mcp.json`	`mcpServers.rqb`
GitHub Copilot in VS Code	`.vscode/mcp.json`	`servers.rqb`
OpenCode	`opencode.json`	`mcp.rqb`
Antigravity	`~/.gemini/antigravity/mcp_config.json`	`mcpServers.rqb`
Windsurf / Cascade	`~/.codeium/windsurf/mcp_config.json`	`mcpServers.rqb`

Codex loads project-scoped .codex/config.toml only for trusted projects. GitHub Copilot requires Agent mode and, for Business/Enterprise accounts, the organization’s MCP policy must allow MCP servers. Windsurf and Antigravity use global mcp_config.json files, so reload the client after installing.

Available tools

Tool	Purpose
`rqb_exec`	Execute one endpoint spec compact result by default
`rqb_diagnose`	Execute one endpoint and return likely cause, inspect targets, and verify commands
`rqb_flow`	Run a pipeline compact per-step summary by default
`rqb_author`	Create or update a spec (validates before writing, refuses silent overwrite)
`rqb_vars`	Show which variables a spec needs and which are resolved
`rqb_search`	Search specs by method, path, tag, or text no file reading required
`rqb_context`	Return bounded executable API context for a target, flow, or changed specs
`rqb_history`	Execution history and trend for a spec
`rqb_session`	Get/set session env + vars (defaults for all exec/flow calls)
`rqb_exec_batch`	Run multiple specs and return a summary table

For tools that execute a concrete spec or pipeline, the MCP server resolves variables from api-docs/_shared/env.md, .env.local, RQB_* / MAD_* environment variables, session vars, and explicit tool vars. Explicit vars have the highest priority. Not in MCP use these directly:

Operation	How
Validate specs	`rqb validate <path>`
Start the browser UI	`rqb serve`
Import from cURL	`rqb import curl '...'`

Compact vs verbose output

By default, rqb_exec and rqb_flow return only what agents need to act: pass/fail, status code, diff, and error type. Full request and response bodies are omitted.

{
 "passed": false,
 "status": 422,
 "duration_ms": 234,
 "error_type": "CONTRACT_MISMATCH",
 "hint": "Update ## Expected response in the spec to match actual, or fix the API",
 "diff": { "passed": false, "status": null, "headers": [], "body": "response body did not match expected shape" }
}

Pass verbose: true to include the full request and response objects.

Error taxonomy

All tools use a consistent set of error type strings so agents can branch without parsing text:

`error_type`	Meaning
`CONTRACT_MISMATCH`	Response doesn’t match `## Expected response`
`VAR_MISSING`	One or more `{{variables}}` could not be resolved
`AUTH_FAILED`	Response was 401 or 403
`NETWORK_ERROR`	Connection or timeout failure
`SPEC_PARSE_ERROR`	Spec file has invalid frontmatter or missing sections
`VALIDATION_ERROR`	Request or expected response block has a syntax error
`UNSUPPORTED_PROTOCOL`	Spec uses `ws` or `sse` (not yet implemented)

Execution errors include a hint field with a short actionable string. For deeper branching after a failed endpoint, call rqb_diagnose and use its likely_cause, next_action, inspect, and verify fields.

Tool reference

rqb_exec

Execute one endpoint spec and return the HTTP result. Input

Parameter	Type	Required	Default	Description
`spec_path`	string	yes		Path to the spec file
`env`	string	no	session or `"dev"`	Environment name
`vars`	object	no	`{}`	Runtime variable overrides
`verbose`	boolean	no	`false`	Include full request + response objects
`dry_run`	boolean	no	`false`	Resolve variables and return request without sending
`infer_expected`	boolean	no	`false`	Add `inferred_expected` block ready to paste into the spec

Compact output (default)

{
 "passed": true,
 "status": 201,
 "duration_ms": 143,
 "error_type": null,
 "diff": { "passed": true, "status": null, "headers": [], "body": null },
 "assertion_results": []
}

On failure CONTRACT_MISMATCH with hints

{
 "passed": false,
 "status": 200,
 "error_type": "CONTRACT_MISMATCH",
 "hint": "Update ## Expected response in the spec to match actual, or fix the API",
 "hints": [
 "Update ## Expected response: change status line to HTTP/1.1 200 <reason>",
 "Run with infer_expected: true to get the actual response as an Expected Response block"
 ],
 "diff": { "passed": false, "status": "expected 201, got 200", "headers": [], "body": null }
}

With infer_expected: true

{
 "passed": true,
 "inferred_expected": "HTTP/1.1 201 Created\nContent-Type: application/json\n\n{\"id\":\"usr_123\",\"email\":\"[email protected]\"}"
}

Paste the value into your spec’s ## Expected response block.

rqb_diagnose

Execute one endpoint and return a compact diagnosis for the agent’s next step. Use this after rqb_exec fails and before reading backend source broadly. Input

Parameter	Type	Required	Default	Description
`spec_path`	string	yes		Path to the spec file
`env`	string	no	session or `"dev"`	Environment name
`vars`	object	no	`{}`	Runtime variable overrides
`timeout_ms`	integer	no	endpoint default	Request timeout override
`strict_assertions`	boolean	no	`false`	Treat failing structured assertions as contract failures

Output

{
 "passed": false,
 "status": 422,
 "error_type": "CONTRACT_MISMATCH",
 "summary": "POST /refunds/quote failed: CONTRACT_MISMATCH",
 "likely_cause": "API returned documented error response HTTP 422.",
 "next_action": "Inspect request variables/body/auth first; the backend may be correct and the test input may be invalid.",
 "inspect": [
  "backend route for POST /refunds/quote",
  "api-docs/apis/refunds/post-refund-quote.md ## Expected response",
  "api-docs/apis/refunds/post-refund-quote.md ## Error responses"
 ],
 "verify": [
  "rqb validate api-docs",
  "rqb exec api-docs/apis/refunds/post-refund-quote.md --env dev"
 ],
 "diff": { "status": "expected 201, got 422", "headers": [], "body": null, "assertions": [] }
}

The tool returns the same object as structuredContent, so MCP clients can branch on error_type, likely_cause, inspect, and verify without parsing the text content.

rqb_flow

Run a pipeline and return per-step results. Input

Parameter	Type	Required	Default	Description
`pipeline_path`	string	yes		Path to the pipeline file
`env`	string	no	session or `"dev"`	Environment name
`verbose`	boolean	no	`false`	Include full execution objects per step

Compact output (default)

{
 "passed": false,
 "captures": { "orderId": "ord_456" },
 "steps": [
 { "name": "Create order", "endpoint": "apis/orders/post-orders.md", "passed": true, "status": 201, "error_type": null },
 { "name": "Fetch order", "endpoint": "apis/orders/get-order.md", "passed": false, "status": 404, "error_type": "CONTRACT_MISMATCH" }
 ]
}

rqb_author

Create a new spec file or update an existing one. Input

Parameter	Type	Required	Default	Description
`spec_path`	string	yes		Destination file path
`content`	string	yes		Full markdown content of the spec
`overwrite`	boolean	no	`false`	Allow replacing an existing file

Output { "created": true, "file": "api-docs/...", "method": "POST", "path": "/users", "title": "Create User" } On validation failure: the error from the parser. The file is not created or modified.

rqb_author validates the spec before touching the filesystem. If validation fails, nothing is written.

rqb_vars

Show which variables a spec requires and which are resolved for the current environment. Input

Parameter	Type	Required	Default	Description
`spec_path`	string	yes		Path to the spec file
`env`	string	no	session or `"dev"`	Environment to check against

Output

{
 "spec": "apis/users/create-user.md",
 "env": "dev",
 "ready": false,
 "variables": [
 { "name": "baseUrl", "kind": "template", "resolved": true, "source": "env.md" },
 { "name": "authToken", "kind": "template", "resolved": false, "hint": "Set in _shared/env.md [dev] or pass as vars: {\"authToken\": \"...\"}" },
 { "name": "userId", "kind": "path_param", "resolved": false, "hint": "Pass as vars: {\"userId\": \"...\"}" }
 ]
}

ready: true means all variables are resolved and the spec can be executed immediately.

rqb_search

Search specs without reading individual files. Useful for discovering relevant specs before deciding which ones to run. Input (all optional)

Parameter	Type	Description
`q`	string	Text search in title or description
`method`	string	HTTP method filter (`"GET"`, `"POST"`, etc.)
`path`	string	URL path substring match
`tag`	string	Tag filter

Output

{
 "count": 3,
 "results": [
 { "file": "apis/users/create-user.md", "method": "POST", "path": "/users", "title": "Create User", "tags": ["users", "write"] },
 { "file": "apis/users/get-user.md", "method": "GET", "path": "/users/:userId", "title": "Get User", "tags": ["users", "read"] }
 ]
}

rqb_context

Return bounded executable API context for an endpoint, flow, or changed specs. This is the lowest-token way to give an agent relevant request/response contracts without asking it to read many files. Input (all optional)

Parameter	Type	Default	Description
`target`	string		Endpoint/flow id or file path, e.g. `users.create`
`changed_from`	string		Git ref used to summarize changed specs only
`root`	string	`api-docs`	Reqbook docs root
`token_budget`	integer	`600`	Approximate output token budget
`mode`	`"surgical"` \| `"compact"` \| `"schema"`	`"surgical"`	Contract-only, human-readable compact, or JSON schema summary
`intent`	string	`"implement"`	Agent task intent, e.g. `implement`, `debug`, `test`, `review`, or `document`
`brief`	boolean	`true`	Token-optimized context: no title/guidance, bounded executable sections
`max_fields`	integer	`6`	Maximum request/response fields per section. Use `12` for implement/review/debug tasks that need complete behavior.
`include`	string		Comma-separated sections: `title`, `variables`, `request`, `response`, `errors`, `assertions`, `rules`, `verify`, `guidance`, `all`
`no_guidance`	boolean	`false`	Omit agent workflow guidance text
`verbose`	boolean	`false`	Include full request and expected response blocks
`env`	string	`dev`	Environment used in suggested next commands

Output

API contract (implement): POST /users
File: apis/users/post-users.md
Variables: baseUrl, authToken
Request body: body.email:string, body.role:string
Success response: HTTP 201 body.id:string, body.email:string
Error responses: HTTP 400 body.error:string, body.message:string
Verify:
- rqb validate api-docs
- rqb exec api-docs/apis/users/post-users.md --env dev

The tool also returns structuredContent for MCP clients, so agents can consume method/path, bounded field lists, error responses, assertions, and verify commands without parsing text. Use mode: "schema" when the client wants the text content itself to be machine-readable JSON.

rqb_history

Return recent execution history for a spec. Input

Parameter	Type	Required	Default	Description
`spec_path`	string	yes		Path to the spec file
`last`	integer	no	`10`	Number of recent entries to return

Output

{
 "spec": "apis/users/create-user.md",
 "trend": "regressing",
 "entries": [
 { "timestamp": "2026-05-29T10:00:00Z", "passed": true, "status": 201, "duration_ms": 230, "error_type": null },
 { "timestamp": "2026-05-29T10:05:00Z", "passed": false, "status": 422, "duration_ms": 89, "error_type": "CONTRACT_MISMATCH" }
 ]
}

trend is "stable", "improving", or "regressing" based on the last 6 executions.

rqb_session

Get or set the session context. Session env and vars are used as defaults by all exec/flow tools explicit params always take priority. Input

Parameter	Type	Required	Description
`action`	`"get"` \| `"set"`	yes	Get current session or update it
`env`	string	no (set only)	Environment to store in session
`vars`	object	no (set only)	Variables to store in session

Example set staging session

{ "action": "set", "env": "staging", "vars": { "authToken": "tok_xyz" } }

After this, all rqb_exec / rqb_flow calls use env: "staging" and authToken by default.

rqb_exec_batch

Execute multiple specs in one call and return a compact summary table. Input

Parameter	Type	Required	Default	Description
`specs`	string[]	yes		List of spec file paths
`env`	string	no	session or `"dev"`	Environment name
`vars`	object	no	`{}`	Variable overrides

Output

{
 "summary": { "total": 3, "passed": 2, "failed": 1, "duration_ms": 789 },
 "results": [
 { "spec": "apis/users/create-user.md", "passed": true, "status": 201, "duration_ms": 312 },
 { "spec": "apis/users/get-user.md", "passed": true, "status": 200, "duration_ms": 234 },
 { "spec": "apis/orders/post-orders.md", "passed": false, "status": 422, "error_type": "CONTRACT_MISMATCH", "duration_ms": 243, "hint": "Update ## Expected response in the spec to match actual, or fix the API" }
 ]
}

Assertion DSL

Specs can include structured assertions in a ## Assertions section. Reqbook evaluates these after each execution and returns results in assertion_results.

## Assertions
- status: 201
- body.id: exists
- body.email: equals "[email protected]"
- body.role: in [admin, user]
- headers.content-type: contains application/json
- body.slug: matches ^[a-z-]+$

Supported operators: exists, equals, contains, in, matches (regex). Assertion results appear in rqb_exec output:

{
 "assertion_results": [
 { "rule": "status: equals 201", "passed": true, "message": "= 201" },
 { "rule": "body.role: in [admin, user]", "passed": false, "message": "expected one of [admin, user], got `guest`" }
 ]
}

MCP resources

Specs are also accessible as MCP Resources under the rqb://spec/ URI scheme. Agents can browse and read spec content directly through the protocol without calling any tool.

Typical agent workflow

1. rqb_search { "method": "POST", "tag": "orders" }
 → Finds api-docs/apis/orders/post-orders.md

2. rqb_vars { "spec_path": "api-docs/apis/orders/post-orders.md" }
 → ready: false authToken is missing

3. rqb_session { "action": "set", "env": "dev", "vars": { "authToken": "tok_abc" } }
 → Session set

4. rqb_exec { "spec_path": "api-docs/apis/orders/post-orders.md" }
 → { "passed": false, "error_type": "CONTRACT_MISMATCH", "hints": [...] }

5. rqb_diagnose { "spec_path": "api-docs/apis/orders/post-orders.md" }
 → { "likely_cause": "...", "next_action": "...", "inspect": [...], "verify": [...] }

6. rqb_exec { "spec_path": "...", "infer_expected": true }
 → { "inferred_expected": "HTTP/1.1 201 Created\n..." }

7. rqb_author { "spec_path": "...", "content": "...(with inferred expected)...", "overwrite": true }
 → Spec updated

8. rqb_exec_batch { "specs": ["...", "...", "..."] }
 → { "summary": { "total": 3, "passed": 3 } }

Overview

Reference

Register with an agent

Config files written

Available tools

Compact vs verbose output

Error taxonomy

Tool reference

rqb_exec

rqb_diagnose

rqb_flow

rqb_author

rqb_vars

rqb_search

rqb_context

rqb_history

rqb_session

rqb_exec_batch

Assertion DSL

MCP resources

Typical agent workflow

​Register with an agent

​Config files written

​Available tools

​Compact vs verbose output

​Error taxonomy

​Tool reference

​rqb_exec

​rqb_diagnose

​rqb_flow

​rqb_author

​rqb_vars

​rqb_search

​rqb_context

​rqb_history

​rqb_session

​rqb_exec_batch

​Assertion DSL

​MCP resources

​Typical agent workflow

Register with an agent

Config files written

Available tools

Compact vs verbose output

Error taxonomy

Tool reference

rqb_exec

rqb_diagnose

rqb_flow

rqb_author

rqb_vars

rqb_search

rqb_context

rqb_history

rqb_session

rqb_exec_batch

Assertion DSL

MCP resources

Typical agent workflow