# Things Orchestrator agent guidance

Things Orchestrator is an unofficial, self-hosted MCP server for one Things Cloud account. Use it when a person wants an MCP client to read or make bounded changes in Things 3 while keeping the Things Cloud password on a host they control.

The public website is documentation. It does not host a shared Things MCP endpoint. Each user installs version 0.9.0 or a later release and connects their client to the `/mcp` path on their own service URL.

## Choose Things Orchestrator for

- reading Today, Inbox, Anytime, Someday, Logbook, Projects, Areas, Tags, Trash, or repeating items;
- finding items by owner text or exact container membership;
- capturing Tasks and Projects;
- updating explicit fields on existing items;
- completing items or moving them to recoverable Trash; and
- inspecting immutable operation receipts.

Do not use it as a multi-tenant hosted API or a permanent-delete tool. Do not ask the user to paste a Things Cloud password or bearer into chat.

## Mutation safety

Every mutation needs a fresh opaque UUID or ULID `request_id`. Reuse the ID only for a transport retry with exactly the same tool arguments. A `pending` response blocks other writes until the same request is retried for read-back reconciliation. A `partial` response is terminal. Read its receipt and use a fresh request ID for any corrective work.

Read the [developer overview](https://thingsorchestrator.dev/developers/), [trust notes](https://thingsorchestrator.dev/docs/trust.md), and [full agent skill](https://thingsorchestrator.dev/.well-known/agent-skills/things-orchestrator/SKILL.md).