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

# MCP reference

> Released Verelyn MCP tools.

# MCP reference

Server: `https://verelyn.com/api/mcp`. Browser OAuth binds every call to the approving reader. All tools are deployed contracts but live use is access dependent.

| Tool                        | Permission                         | Input                                                        | Result and effect                                            |
| --------------------------- | ---------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| `get_newsroom_summary`      | `newsroom_read` or `mandate_write` | none                                                         | Stored readiness and latest sent edition; no editorial work. |
| `get_briefing`              | `newsroom_read` or `mandate_write` | optional positive `edition_number`                           | Stored sent edition; no read mark.                           |
| `get_mandate`               | `mandate_write`                    | none                                                         | Stored mandate and coverage.                                 |
| `submit_mandate_correction` | `mandate_write`                    | `command_id`, `expected_revision`, `statement`, `provenance` | Records a dated, confirmed correction when applied.          |
| `get_updates`               | `newsroom_read` or `mandate_write` | optional opaque `cursor`                                     | Already-sent updates; records retrieval.                     |
| `start_monitor`             | `mandate_write`                    | exactly one `item_id` or `alert_id`                          | Creates a followed situation.                                |
| `list_monitors`             | `mandate_write`                    | none                                                         | Lists the reader's situations.                               |
| `set_monitor_state`         | `mandate_write`                    | `monitor_id`, `active`/`paused`/`stopped`                    | Changes state; stop is irreversible.                         |
| `start_onboarding`          | `onboarding_write`                 | unique `command_id`                                          | Starts an assistant-owned draft; no activation.              |
| `get_onboarding`            | `onboarding_write`                 | `draft_id`                                                   | Reads the current draft.                                     |
| `submit_onboarding_answer`  | `onboarding_write`                 | draft, command, revision, action, provenance, answer fields  | Records an answer or correction for reader review.           |

## Exact write inputs

All fields are required unless marked optional. UUID fields are `command_id`, `draft_id`, `target_answer_id`, `item_id`, `alert_id`, and `monitor_id`. `question_id` is a non-empty string of at most 160 characters; use the value returned by the service unchanged.

`submit_mandate_correction`:

```json theme={null}
{
  "command_id": "00000000-0000-4000-8000-000000000101",
  "expected_revision": 4,
  "statement": "Follow Example Robotics less closely.",
  "provenance": "reader_words"
}
```

`expected_revision` is a non-negative integer; `statement` is 1–2,000 characters; `provenance` is `reader_words` or `assistant_suggestion`. The read tools do not expose the current revision, so use the web editor unless a supported product flow supplied it.

`start_monitor` takes exactly one field, never both:

```json theme={null}
{"alert_id":"00000000-0000-4000-8000-000000000201"}
```

`set_monitor_state`:

```json theme={null}
{"monitor_id":"00000000-0000-4000-8000-000000000202","state":"paused"}
```

`state` is `active`, `paused`, or `stopped`. `get_updates.items[].id` can supply an eligible alert ID. `get_briefing` does not expose edition item IDs; use the web edition for that starting path.

`start_onboarding`:

```json theme={null}
{"command_id":"00000000-0000-4000-8000-000000000301"}
```

`get_onboarding`:

```json theme={null}
{"draft_id":"00000000-0000-4000-8000-000000000302"}
```

`submit_onboarding_answer` always requires `draft_id`, UUID `command_id`, non-negative `expected_revision`, `action`, and `provenance` (`reader_answer` or `assistant_suggestion`). `action` is `answer`, `correct`, `skip`, or `retry`:

* `answer`: also requires `question_id`, `question_text`, and non-empty `answer`.
* `correct`: also requires UUID `target_answer_id`, `question_id`, `question_text`, and non-empty `answer`.
* `skip`: also requires `question_id` and `question_text`.
* `retry`: adds no action-specific field.
* Optional `timezone` must be an IANA time-zone name such as `America/Argentina/Cordoba`.

An accepted answer can return this `structuredContent` shape; later states may instead include `next_question`, `continue_url`, or a public `error`:

```json theme={null}
{"draft_id":"00000000-0000-4000-8000-000000000302","revision":5,"status":"collecting","answers":[],"accepted":{"command_id":"00000000-0000-4000-8000-000000000303","answer_id":"00000000-0000-4000-8000-000000000304"},"alerts_notice":null}
```

## Result envelopes

Success returns MCP `structuredContent` matching the tool's output schema plus a short text summary. For example, `set_monitor_state` returns:

```json theme={null}
{"monitor":{"id":"00000000-0000-4000-8000-000000000202","title":"Example Robotics financing","followed":null,"state":"paused","created_at":"2026-09-25T12:00:00Z","last_update_at":null,"close_suggested":false}}
```

A tool failure sets `isError: true` and returns public text, for example `invalid_cursor: That cursor is not one this newsroom issued.` It does not return the REST JSON error envelope.

Common public errors are `unauthorized`, `permission_denied`, `invalid_request`, `invalid_input`, `briefing_unavailable`, `revision_conflict`, `invalid_cursor`, `not_found`, `monitor_stopped`, `limit_reached`, `unsupported_coverage`, `evaluation_unavailable`, `onboarding_unavailable`, and `internal_error`. See [Troubleshooting](/help/troubleshooting).

Identifiers and cursors are opaque. Examples use synthetic values only.