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
- Before any action with effects outside the conversation, the agent calls
request_approvalwith what it intends to do. - It acts only if the returned status says it may, and with the edited payload if one came back.
- After the attempt it calls
report_resultonce 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
| Parameter | Type | Required | Meaning |
|---|---|---|---|
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
| Field | Meaning |
|---|---|
status | The request's status when the tool returns. See Handling responses for what each one means. |
edited_payload | The 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. |
explanation | The sentence that says which rule decided the outcome. |
request_id | The 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
| Parameter | Type | Required | Meaning |
|---|---|---|---|
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
| Field | Meaning |
|---|---|
request_id | The request the report was filed for. |
status | The request's new status: executed or failed. |
report_id | The 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
| Parameter | Type | Required | Meaning |
|---|---|---|---|
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
| Field | Meaning |
|---|---|
outcome | What the rules would decide: auto_allow, hold, require_approval or prohibit. |
status | The status a real request would start with. |
matched_rule_id | The id of the rule that would decide, or null when no rule matches. |
hold_minutes | The length of the hold when the outcome is hold, otherwise null. |
explanation | The sentence that says which rule would decide. |
Waiting inside request_approval
- The tool submits the request and then waits for an answer for up to
wait_seconds. The default is 300 seconds. - It returns as soon as the request is approved, denied, released, cancelled, expired, auto allowed or prohibited.
- If the time runs out first, it returns the status "pending" or "held". That is not an answer. The agent must not act, and should tell you and ask whether to keep waiting.
- Each call of the tool creates a new request. To keep waiting on the same request, an agent that can make HTTP calls uses the wait route with the
request_id.
When a tool does not return a result
| The tool answers with | Meaning |
|---|---|
| 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: API overview
Next: Handling responses
All help pages
Inbox
- Read a request
- Approve, deny or edit a request
- Held actions
- Expired requests and history
- Request statuses
Rules
- How rules work
- The default rules
- Write a rule in plain English
- Build a rule with the form
- Reorder, enable and disable rules
- Suggested rules
- Set a default policy for an agent
- Export your rules
Teams
Ledger
- What the ledger is
- Browse and filter the ledger
- Export and verify the ledger
- Payload retention
- Monthly statements
Billing
Account and security
- Change your password
- Two-factor authentication and recovery codes
- Rotate or revoke an agent key
- How your data is protected
- Closing an account