MCP tools

The MCP server 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.

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.

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.