> ## Documentation Index
> Fetch the complete documentation index at: https://docs.markapidown.net/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Ten structured tools for MCP-compatible coding agents: exec, diagnose, flow, author, vars, search, context, history, session, and exec_batch. Surgical context by default; verbose mode for debugging.

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

<Steps>
  <Step title="Install a project or agent config">
    ```bash theme={null}
    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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Verify registration">
    ```bash theme={null}
    claude mcp list
    codex mcp list
    opencode mcp list
    ```

    Expected Claude Code output:

    ```text theme={null}
    rqb: rqb mcp - ✓ Connected
    ```
  </Step>
</Steps>

### 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`                 |

<Note>
  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.
</Note>

***

## 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.

```json theme={null}
{
 "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)**

```json theme={null}
{
 "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**

```json theme={null}
{
 "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`**

```json theme={null}
{
 "passed": true,
 "inferred_expected": "HTTP/1.1 201 Created\nContent-Type: application/json\n\n{\"id\":\"usr_123\",\"email\":\"ada@example.com\"}"
}
```

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**

```json theme={null}
{
 "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)**

```json theme={null}
{
 "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.

<Note>
  `rqb_author` validates the spec before touching the filesystem. If validation fails, nothing is written.
</Note>

***

### 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**

```json theme={null}
{
 "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**

```json theme={null}
{
 "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**

```text theme={null}
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**

```json theme={null}
{
 "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**

```json theme={null}
{ "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**

```json theme={null}
{
 "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`.

```markdown theme={null}
## Assertions
- status: 201
- body.id: exists
- body.email: equals "ada@example.com"
- 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:

```json theme={null}
{
 "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

```text theme={null}
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 } }
```