# MCP tools

> Every tool, prompt and resource the Deference MCP server offers.

The [MCP server](https://deference.si/docs/coding-tools/mcp) lists every tool for an OAuth connection, including a read-only connection. Calling a Write tool without Write returns HTTP 403 with an `insufficient_scope` challenge, asking the client to step up to Write. An API key with MCP access gets only the Read tools.

Money is a decimal string in US dollars. Times are ISO 8601 in UTC. An error starts with a code and a colon, such as `budget_exhausted:`. The codes are listed in [Troubleshooting](https://deference.si/docs/coding-tools/mcp#troubleshooting).

### Read

* `deference_get_balance`: Shows the account's credit and free credit, and this connection's spend budget. No inputs.
* `deference_list_models`: Lists models with their prices and whether free credit can pay for them. Inputs: search, category, sort, ids, output, min_context, max_input_price, max_output_price, free_credit, limit, cursor.
* `deference_get_model`: Shows one model's details and prices, and estimates a call's cost from token counts. Inputs: id, input_tokens, output_tokens.
* `deference_get_usage`: Sums spend, requests and tokens over a range, broken down by model, key or client. Inputs: range, key_id, group_by.
* `deference_list_requests`: Lists the account's requests with model, tokens, cost and status, or finds one by id. Inputs: request_id, key_id, model, status, since, limit, cursor.
* `deference_list_keys`: Lists the account's API keys, masked, with limits, spend and expiry, and marks the connection's spend key. Inputs: include_inactive.
* `deference_get_key_status`: Shows one key's status, spend and what it has left. Inputs: key_id.
* `deference_search_docs`: Searches these docs, or reads one page as Markdown. Inputs: query or page.

### Write

* `deference_run_model`: Runs a model from the connection's budget and states the cost. Inputs: model, input, system, max_output_tokens, temperature, web_search, max_cost_usd, idempotency_key. Connections only.
* `deference_generate_image`: Generates one image from the connection's budget, returns a preview and a link to the original for 24 hours, and states the cost. Inputs: prompt, model, shape, max_cost_usd, idempotency_key. Connections only.
* `deference_create_key`: Creates a capped, expiring key, returns it once, and adds setup for Claude Code, Codex and OpenAI-compatible clients. Inputs: name, limit_usd, expires_in_days. Connections only.
* `deference_rotate_key`: Replaces a key the app created with a new secret, and the old key stops at once. Inputs: key_id. Connections only.
* `deference_revoke_key`: Turns off a key the app created. Inputs: key_id. Connections only.

`input` on `deference_run_model` is a nonempty prompt or 1 to 40 messages, each with `role` set to `user` or `assistant` and nonempty `content`. Input text and optional `system` together hold at most 64,000 characters. `max_output_tokens` is an integer from 1 to 16,384, with a default of 1,024. `temperature` ranges from 0 to 2, and `web_search` is an optional boolean. Larger inputs belong in code that calls the API with a key.

`deference_generate_image` requires a `prompt` of 1 to 4,000 characters. Optional `shape` is `square`, `landscape` or `portrait`, with `square` as the default. Both paid tools require a `model` id of 1 to 200 characters.

Paid calls take `max_cost_usd` as a decimal string, with up to three digits before the decimal point and six after it. The value ranges from $0 to $5 and defaults to $0.50. Each call requires an `idempotency_key` of 8 to 64 ASCII letters, digits, hyphens or underscores.

The key identifies a call for the same account and tool, across connections. Retry with identical inputs, including optional fields and `max_cost_usd`. Changed inputs return `idempotency_conflict`, and a pending call returns `still_running`. Call records are retained for 90 days. While the record exists, a completed retry never charges again. A failed call that cost nothing can run again with the same key.

Deference never stores text model outputs. A retry of a finished `deference_run_model` call returns its receipt with `output_text` set to null. Before the image expires, a retry of a finished `deference_generate_image` call returns its receipt and a fresh download link, without the preview. The previous link stops working, and the original 24-hour expiry is unchanged. After expiry, the retry returns the receipt with no download link.

`deference_rotate_key` and `deference_revoke_key` refuse the connection's spend key. Manage that key in [Agents](https://deference.si/agents).

### Prompts

* `setup_coding_tool`: Sets up a coding tool with a new key. Arguments: client, one of claude-code, codex, cursor or other.
* `pick_model`: Finds and compares up to 3 models for a task. Arguments: task, budget_usd.
* `spend_report`: Summarizes spend by model and client, and lists failed requests. Arguments: range, one of 24h, 7d or 30d.

### Resources

* `deference://docs/{+path}`: Every docs page as Markdown, for example `deference://docs/coding-tools/mcp`. The list names each page with its title.