# MCP

> Updates to the MCP server and its tools, newest first.

## 2026-10-25 · `1.0.0`

**MCP server 1.0.0.** Version 1.0.0 of the Filmo MCP server.

### Added

- `retryAfter` on the `429 rate_limited` problem (REST and MCP): seconds to wait before retrying, the same value as the `Retry-After` header; `detail` says it too.
- MCP tool results carry in `meta` what REST sends as headers: `meta.idempotencyKey` (the key the call ran with, yours or the one the server generated), `meta.idempotentReplay` (`true` when the result is the stored response of an earlier call with the same key) and `meta.rateLimit` (`limit`, `remaining`, `reset`).
- MCP: `_meta["anthropic/requiresUserInteraction"]: true` on the tools that cannot be undone (deletes, cancellations, voids, validations of fiscal documents, signing a contract) and on the four that must carry their own `idempotencyKey`.
- MCP: the `WWW-Authenticate` header of the `401` of `/api/v1/mcp` carries `scope` with the read scopes, so clients ask for read access by default.

### Changed

- MCP errors: a failed `tools/call` returns `isError: true` with the RFC 9457 problem as JSON in `content[0].text`, and no `structuredContent`. The official MCP SDKs validate `structuredContent` against the success `outputSchema` even on errors.
- MCP `outputSchema` no longer sets `additionalProperties: false`: a field added to a response is a compatible change and does not fail validation in the client.
- MCP annotations: `destructiveHint: true` on the validations of invoices, credit notes, contracts and supplier invoices, on `filmo_contracts_sign`, `filmo_purchase_orders_receive`, `filmo_orders_line_items_return` and `filmo_treasury_payments_create`. `filmo_ai_ask` is no longer `readOnlyHint` (each call spends AI credits) and keeps `openWorldHint`.
- OAuth consent: only read scopes are pre-selected (the ones the client asks for, or all of them if it asks for none); write scopes, `workflows:run` and `ai:ask` always start unselected and the administrator turns them on. `scope` is optional on `/oauth/authorize`, and unknown scopes are ignored instead of failing the request.
- OAuth in production: the issuer, the endpoints and the protected `resource` are always on `https://app.filmo.io`; `/api/v1/mcp` and the `.well-known` documents on any other production host answer `308` to it.
- MCP server `instructions`: the essentials (safe retries, how errors arrive, dates, money, `ifMatch`) come first, within the first 2,048 characters; JSON-RPC error messages are in English.

---

Canonical URL: https://docs.filmo.io/changelog/mcp  
Last updated: 2026-10-25