Help: For agent builders

MCP tools

The MCP server gives an agent 3 tools: request_approval, report_result, check_policy. It is hosted with funwatcher: there is nothing to install. An MCP client connects to it over the internet and sends the agent's key with every request. The server passes each tool call to the funwatcher API with that key and has no other access, so a client can only act as its own agent.

To connect a client, see Connect an agent. It gives the address to connect to, the header that carries the key and the steps for each kind of client. For the HTTP routes behind the tools, see API overview.

How an agent uses the tools

  1. Before any action with effects outside the conversation, the agent calls request_approval with what it intends to do.
  2. It acts only if the returned status says it may, and with the edited payload if one came back.
  3. After the attempt it calls report_result once with what happened.

check_policy is optional. It asks what the rules would decide without submitting anything.

The tools tell the agent what it may do. They cannot stop an agent that does not call them or ignores the answer, and a report is the agent's own statement.

request_approval

Call this BEFORE any consequential action on the user's behalf: a payment, a message to someone, a deletion, a public post, a signature, an account or permission change, or anything else with effects outside this conversation. It submits the proposed action to funwatcher, where the account's policy and a human reviewer decide, and waits for the answer. Act only on the returned status. approved, released or auto_allowed: proceed. denied, prohibited, expired or cancelled: do not act, tell the user and stop. pending or held: no answer yet, do not act, tell the user and ask whether to wait longer. If edited_payload is not null, a reviewer changed the action: execute exactly the edited payload and nothing else, not the payload you proposed. After executing (or failing to), call report_result with the request_id.

Parameters

ParameterTypeRequiredMeaning
action_type one of payment, message, delete, post, sign, account_change, other yes What kind of action is proposed.
summary text yes One sentence a human reviewer reads to decide; name the counterparty and the effect.
payload JSON object yes The exact parameters you will execute with, as a JSON object. If a reviewer edits them, you receive the edited object back.
counterparty text no Who or what the action is directed at: a payee, recipient, account or resource name.
amount_minor whole number no Amount in the currency's minor units (cents, pence). Send together with currency or not at all.
currency text no ISO 4217 code, three letters, for amount_minor.
reversible true or false no, default true Whether the action can be undone afterwards.
wait_seconds whole number no, default 300 How long to wait for a decision before returning the current status.

Returns

FieldMeaning
statusThe request's status when the tool returns. See Handling responses for what each one means.
edited_payloadThe payload as a reviewer changed it, or null when it was not changed. When it is not null, the agent must act with this payload and not the one it proposed.
explanationThe sentence that says which rule decided the outcome.
request_idThe id to pass to report_result.

report_result

Report what happened after an approved, released or auto_allowed action was attempted: outcome executed or failed, an optional external reference (transaction id, message id, URL) and an optional detail. Call this once per request_id, right after the attempt.

Parameters

ParameterTypeRequiredMeaning
request_id text yes The request_id returned by request_approval.
outcome one of executed, failed yes executed if the action was carried out, failed if it was attempted and did not succeed.
external_ref text no An identifier in the external system: transaction id, message id, URL.
detail text no What happened, especially for a failure.

Returns

FieldMeaning
request_idThe request the report was filed for.
statusThe request's new status: executed or failed.
report_idThe id of the stored report.

check_policy

Dry run: ask what the account's policy would decide for a proposed action without submitting it. Returns the outcome (auto_allow, hold, require_approval or prohibit), the rule that matched and an explanation. Nothing is recorded and no one is notified; use request_approval to actually ask.

Parameters

ParameterTypeRequiredMeaning
action_type one of payment, message, delete, post, sign, account_change, other yes What kind of action is proposed.
payload JSON object yes The parameters you would execute with, as a JSON object.
counterparty text no Who or what the action is directed at.
amount_minor whole number no Amount in minor units; send together with currency or not at all.
currency text no ISO 4217 code, three letters.
reversible true or false no, default true Whether the action can be undone afterwards.

Returns

FieldMeaning
outcomeWhat the rules would decide: auto_allow, hold, require_approval or prohibit.
statusThe status a real request would start with.
matched_rule_idThe id of the rule that would decide, or null when no rule matches.
hold_minutesThe length of the hold when the outcome is hold, otherwise null.
explanationThe sentence that says which rule would decide.

Waiting inside request_approval

When a tool does not return a result

The tool answers withMeaning
Plain text starting "funwatcher is unavailable (HTTP 503)"Maintenance mode is on. No request was created. The agent must not act and can try again later.
An error containing "HTTP 401: Invalid or revoked agent key."The key in the client's configuration was revoked, or its agent was. A client with a wrong key is refused when it connects, with HTTP 401.
An error starting "Could not reach funwatcher at"The MCP server could not reach the funwatcher API. Only the operator of the deployment can fix this.
Any other error starting "funwatcher API refused"The API rejected the call. The text carries the API's own message, for example "Request not found."

See Handling responses and Troubleshooting.

Previous:
Next:

All help pages

Inbox

Rules

Teams

Ledger

Billing

Account and security

For agent builders

Troubleshooting