# MCP and OAuth

The Streamable HTTP endpoint is `https://ink.ego.ist/mcp`. [ChatGPT, Claude and Claude Code setup](https://ink.ego.ist/docs/integrations) use this same endpoint.

## Authorize a client

Discover the [protected resource metadata](https://ink.ego.ist/.well-known/oauth-protected-resource) and [authorization server metadata](https://ink.ego.ist/.well-known/oauth-authorization-server). Public clients use `authorization_code` with S256 PKCE, the MCP resource URL as the resource audience, and either dynamic client registration (DCR) or a client ID metadata document. Discover the authorization, token, registration and revocation URLs from this metadata.

The person signs in and explicitly consents. The only scope is `ink.rewrite`, covering Ink account status, available models, writing tools and owned jobs and results. It grants no Passport memory access. Signup and subscription handoffs do not authorize a client. Refresh tokens rotate; use the newly returned token after each refresh.

Registration allows 30 requests per IP per hour. MCP allows 120 requests per minute per connected user and client. New rewrite jobs share 10 per minute per user across clients. Wait for `Retry-After` when supplied.

## Tools

`ink_get_status`, `ink_rewrite_text`, `ink_write_text`, `ink_get_job`, `ink_get_result`, `ink_cancel_job`

Call `ink_get_status` to check setup and available words. Use `ink_rewrite_text` with `text`, a UUID `idempotency_key` and optional `settings`. Strength defaults to `balanced`; `light` and `strong` are also available. Context is `general`, `work`, `casual` or `academic`; formality is `auto`, `more formal` or `less formal`.

Rewrite input allows 20,000 words and 200,000 characters. Optional `locks` and `unlocks` contain verbatim input strings. Each array allows 100 strings with 20,000 total characters across both arrays. Locks preserve wording; unlocks release automatic highlights, including nested spans. Missing or invalid entries return a validation error. Changing text, settings, mode, profile or locks requires a new idempotency key.

Tools return `setup_required` or `quota_exceeded` with a link to [plans](https://ink.ego.ist/plans). Relay the message and link to the person. [Policies](https://ink.ego.ist/docs/policies) describes `terms_required` and feedback sharing. Feedback tools are available only to the Ink widget on ChatGPT and Claude, not as model-visible tools.

## Meaning checks

Ink silently checks rewrite meaning with OpenAI when configured. Every changed candidate is checked, including retries. A meaning finding can use the section's single shared retry, with source-quote hints. Deterministic guards take precedence when choosing a candidate, then fewer material or critical findings win, with the retry winning a tie. Light and balanced deliver persistent meaning problems silently. Strong keeps and refunds a source section through `sections_kept` only when the chosen candidate still has a critical added claim, changed fact or speaker problem. Material findings are delivered silently; dropped findings can trigger a retry and affect selection but do not keep source by themselves. Unavailable checks fail open. Older saved policies keep their behavior.

## Write from a prompt

Use `ink_write_text` with `prompt` and a UUID `idempotency_key`. Put all instructions in the prompt. Prompts allow 6,000 words, with up to 4,000 output words. Ink reserves available words up to the output cap, charges actual output words and refunds the remainder. Failed or cancelled prompt jobs refund the full reservation. Use a fresh key for another version. Rewrite fidelity checks apply only to rewrites.

## Follow progress

Poll `ink_get_job` and `ink_get_result`. Wait two seconds while `queued` or `starting_model`, then one second while `writing`, `rewriting` or `validating`. Cold starts can take a few minutes. `blocks` contains ordered completed previews; missing indices are pending. `progress` has `phase`, `blocks_done` and `blocks_total`. Partial blocks are not final output. Warnings and `change_summary` are final only.

`completed`, `completed_with_warnings` and `needs_review` are finished results. Deliver warnings with the output. For `details_added`, `first_person_added` or `sections_kept`, do not retry automatically. `failed` has no usable result; `cancelled` is stopped. Use `ink_cancel_job` to request cancellation, then poll until terminal. After text expiry, `output` is absent and `blocks` is empty.

On `details_added`, deliver the output with its warning listing added details. The message is "Check added details before use: ...". On `first_person_added`, deliver the output with its warning listing added first-person words. The message is "Added first-person wording: ..." or, when the list is absent, "Added first-person wording. Check the rewrite.". Light and balanced deliver persistent first-person additions with `completed_with_warnings`; strong keeps the affected source section and refunds it through `sections_kept`. Read the [first-person rules and quotation limit](https://ink.ego.ist/docs/api#first-person-wording).

## Revoke access

Revoke through the discovered revocation endpoint, or choose Disconnect in [Connections](https://ink.ego.ist/app/connections). Disconnect removes the assistant's Ink access. It does not cancel a subscription.
