> For AI assistants: read [llms.txt](https://docs.saturation.io/llms.txt) first for the complete documentation map, API contract, and endpoint Markdown files.

# MCP

Use the remote server at `https://mcp.saturation.io/mcp`. MCP applies the same workspace permissions as the REST API.

OAuth resource metadata is at `https://mcp.saturation.io/.well-known/oauth-protected-resource`.

Remote MCP clients use that metadata to authorize. A Saturation API token can also be sent as `Authorization: Bearer <token>`.

## Tools

The server exposes seven tools.

| Tool | Use it for |
|---|---|
| `search` | Broad text discovery across documents and projects. |
| `fetch` | Open one result returned by `search`. |
| `find` | Find workspace records and their links. |
| `read` | Read a record, document, budget, or banking view. |
| `query` | Ask a read-only question about a budget or ledger. |
| `write` | List and run available changes. |
| `upload` | Add a document from a public HTTPS URL. |

The seven-tool contract stays stable as API coverage grows. Permissions still apply to every call. A connection never gains more access than its user or token has in Saturation.

## Purchase orders

Use `find` with `target: "purchase_order"` to locate an order, then pass its `purchase_order:` ref to `read`.

```json
{ "query": "Camera package", "target": "purchase_order", "mode": "search" }
```

```json
{ "ref": "purchase_order:PO-77", "target": "purchase_order" }
```

The read returns the PO amounts and lines. Use REST when you need the purchase order Timeline or an exact transaction link.

Use `find` with `target: "payment"` to locate a payment, then pass its `payment:` ref to `read`. Payment requests remain a separate REST resource. Use REST when you need linked records or Timeline.

Call `write` with `{}` to list available changes. Ask for one change by name to see its required fields before running it.

```json
{}
```

```json
{ "op": "purchaseOrdersCreate" }
```

Creates receive retry identity automatically. An identical retry returns the first result.

## Next

- [API Reference](/api-reference.md): Purchase Orders, Payment Requests, Payments, and their exact schemas.
- [Errors](/errors.md): public error codes and retry guidance.