Errors, outages and changes

An agent can only recover from a problem if it knows what happened. Octri's MCP server tells agents why a call failed, whether your API is down, and what has changed since they last connected.

Errors that explain the fix

When a call fails, the agent receives How to fix this call, with the status, beneath the request it made. It gets what it needs to correct itself: the field at fault, the error code, how long to wait on a 429, and whether a different argument can help at all or the credential has to change.

That guidance comes from three places, most specific first:

Source	Example
The endpoint	Response descriptions in your spec, and error guides in API Studio that name the status
Your project	What you write under Error guidance by status
Octri	A built-in hint for the status

Writing your own guidance

In MCP Studio, under Error guidance by status, choose Add status and say what an agent should do:

409: The invoice is already paid. Read it and report its status instead of retrying.

This helps most with statuses that mean something specific in your API, such as a 402 or a 409.

Local servers can turn this off with <PREFIX>_ERROR_GUIDES=0.

Outage warnings

If monitoring knows your API is down, a tool says so, and the agent can stop retrying and tell the person. Turn on Warn agents about outages in MCP Studio. It needs monitoring and uptime checks on your endpoints.

The server only reports what the monitor saw. It reports an outage when both of these are true:

The monitor's latest result for that endpoint is down
The call itself failed, with a 5xx, a timeout or no answer

A 4xx, a slow-but-working endpoint, an old monitor result or an unreachable monitor all return the ordinary result. Calls are never held back before they're sent.

If every check on your API's address is down, and there are at least two, that counts as an outage for tools with no check of their own.

When this doesn't apply

Warnings apply when the server calls the same address the monitor checks, so they don't apply if someone overrides the base URL. Self-hosted servers don't receive them when your docs are behind access control.

Change notices

Every publish that changes the tools agents are served is a numbered release, listed under Recent tool releases. Turn on Tell agents what changed and:

A tool that changed since an agent last connected says so at the top of its description.
The agent is told what was added, renamed or removed, and can call what_changed for the details.
Calling a renamed tool by its old name returns a pointer to the new one.

Hosted servers remember where each signed-in person or installation left off. A local server keeps its place in a small state file on the machine.

Practice mode

To let someone try your tools with fake responses and no real effects, see practice mode.

From the CLI

octri mcp changes lists what agents were told changed, and octri mcp outages shows which tools sit behind a failing endpoint. octri mcp outages --fail stops a CI job while any does.