# Remoko MCP Tools Reference

> The Remoko MCP server is a personal decision inbox. Agents create requests; only the human owner — from the iOS app — can answer them. This page lists every tool and the reliability contract agents must follow.

Canonical HTML page: https://remoko.app/docs

## Connection

- Transport: remote MCP over Streamable HTTP (stateless POST). GET/SSE connections are not supported — configure your client for Streamable HTTP.
- Endpoint URL and token: from the **Connect** tab in the Remoko iOS app.
- Auth header on every request: `Authorization: Bearer remoko_tok_...`

## Start here

Call `how_to_use` first. It returns the authoritative guide for the connected server: reliability contract (idempotency, versions, processed acknowledgments), tool list, and metadata.

## Tools

### Creating requests

| Tool | Purpose |
|---|---|
| `ask_question` | Ask the owner a question. Supports predefined choices or free text. |
| `request_approval` | Propose an action and wait for approve/deny. Include a risk level (low / medium / high / critical), consequences, and a recommendation. |
| `notify_user` | Send a check-in / FYI. No response required. |
| `request_feedback` | Ask the owner for open-ended feedback on work in progress. |

Creates are **idempotent** — supply an idempotency key so retries don't duplicate requests.

### Reading responses

| Tool | Purpose |
|---|---|
| `get_response` | Fetch the owner's response to a specific request. |
| `list_pending` | List requests still awaiting the owner's answer. |
| `list_unprocessed` | List answered requests the agent has not yet acknowledged. Call this on startup to recover after a restart. |

### Lifecycle

| Tool | Purpose |
|---|---|
| `update_request` | Modify an existing request. This bumps the request version; any in-flight response to the old version is rejected. |
| `cancel_request` | Cancel a request that is no longer relevant. |
| `mark_processed` | Acknowledge that the agent has acted on a response. Required for reliable delivery. |
| `report_execution` | Report execution status (executing / completed / failed) so the owner sees the outcome of their decision. |

## Rules agents must follow

1. **You can never answer on the owner's behalf.** Agent tokens are scoped to create/update/read. There is no tool that submits an answer.
2. **Respect versions.** Owner responses are bound to the exact request version they saw. If you update a request, expect responses to the old version to be rejected.
3. **Acknowledge processing.** After acting on a response, call `mark_processed`. Use `list_unprocessed` at startup to recover.
4. **Set honest risk levels.** High and critical approvals get no lock-screen quick actions and are excluded from bulk approval — do not downgrade risk to get faster answers.
5. **Remoko is a mirror, not the source of truth.** Re-validate decisions against your primary system state before executing.

## Sitemap

- [Overview & quickstart](https://remoko.app/docs/index.md)
- [Security model](https://remoko.app/docs/security.md)
- [FAQ](https://remoko.app/docs/faq.md)
- [Machine index](https://remoko.app/llms.txt)