# Propose a change (`mttr_propose`)

Updated October 24, 2026.

## What does mttr_propose do?

Before a change goes out on a site set to approve, proposes it to you. mttr emails what the change is, the rule and pages, and an Approve and a Decline link. A key may make this call on the sites it has claimed.

Who may call it: Your claimed sites.

## When to use it

- A site is set to approve and the assistant has a change ready.

## What you ask

You might say: “Propose the sources change for example.com before you deploy it.”

```
mttr_propose({ site: "example.com", title: "Lead each service page with its answer", summary: "Moves the price and the area served into the first paragraph of each service page.", rule: "answer-first", pages: "/drains,/grading", diff: "--- a/app/drains/page.tsx\n+++ b/app/drains/page.tsx" })
```

| Argument | Type | Needed | What it is |
| --- | --- | --- | --- |
| `site` | Text | Yes | The site, as a domain such as example.com. |
| `title` | Text | Yes | What the change is, in a few words on one line, at most 120 characters. |
| `summary` | Text | Yes | What the change does and why, in a few sentences the person can judge, at most 2000 characters. |
| `rule` | Text | No | The mttr rule it answers, by id, such as answer-first. Leave it out for a change no rule names. |
| `pages` | Text | No | The pages it changes, as paths separated by commas, such as /pricing,/about. At most 20; none for the whole site. |
| `diff` | Text | No | The change as a unified diff, at most 20,000 characters. Shown to the person, never applied by mttr. |

## What comes back

- The proposal’s id, to check with Where a proposal stands.
- Each link works once and lapses after 72 hours.

A sample, with made-up sites and figures:

1. Proposed
2. Emailed to you (here)
3. Approved
4. Deployed

Proposal p_7 is waiting for you. Deploy only once it says approved.

## Over HTTP

```
curl -X POST "https://mttr.si/api/v1/account/proposals" \
  -H "Authorization: Bearer $MTTR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"site":"example.com","title":"Lead each service page with its answer","summary":"Moves the price and the area served into the first paragraph of each service page.","rule":"answer-first","pages":"/drains,/grading","diff":"--- a/app/drains/page.tsx\n+++ b/app/drains/page.tsx"}'
```

## When it fails

| When | Status | What to do |
| --- | --- | --- |
| Your assistant has no key yet | 401 over MCP | Sign up with `mttr_signup`, then connect again with the key it gives. |

## Sources

- [Model Context Protocol: tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tools), Model Context Protocol: How an assistant calls a tool.

The call in full: [mttr_propose in the API reference](https://mttr.si/docs/reference#mttr_propose).

## Goes with

- [Where a proposal stands](https://mttr.si/docs/tools/proposal.md)
- [Approvals on or off](https://mttr.si/docs/tools/approvals-set.md)