# MCP server > Let your coding agent check credit, pick and run models within a budget, and manage its own API keys. Deference's MCP server lets your coding agent work with your account at `https://deference.si/api/mcp`. Connect it once, and the agent checks your credit, picks models by price, runs them within a budget you set, and creates its own capped API keys. Adding credit stays with you. Any client that supports remote MCP servers with OAuth can connect, including Cursor and VS Code. ## Connect Claude Code 1. Add the server for every project, then sign in. ```bash claude mcp add --transport http --scope user deference https://deference.si/api/mcp claude mcp login deference ``` 2. Your browser opens on Deference. Sign in if asked, then select **Authorize**. Inside Claude Code, run `/mcp`, pick `deference` and choose **Authenticate** to do the same. `--scope user` makes the server available in every project, because your credit belongs to your account, not to a repository. See the [Claude Code docs](https://code.claude.com/docs/en/mcp). ## Connect Codex 1. Add the server, then sign in. ```bash codex mcp add deference --url https://deference.si/api/mcp codex mcp login deference ``` 2. Your browser opens on Deference. Select **Authorize**. See the [Codex docs](https://learn.chatgpt.com/docs/extend/mcp?surface=cli). The command writes this to `~/.codex/config.toml`: ```toml [mcp_servers.deference] url = "https://deference.si/api/mcp" ``` ## Connect another client The clients below connect over HTTP and sign in with OAuth. Where a client has a sign-in command, its section names it. On Deference, select **Authorize**. ### Cursor Add the server to `~/.cursor/mcp.json`. See the [Cursor docs](https://cursor.com/docs/mcp). ```json { "mcpServers": { "deference": { "url": "https://deference.si/api/mcp" } } } ``` ### VS Code Add the server to `.vscode/mcp.json` in your workspace, or run **MCP: Add Server** from the Command Palette. See the [VS Code docs](https://code.visualstudio.com/docs/agents/reference/mcp-configuration). ```json { "servers": { "deference": { "type": "http", "url": "https://deference.si/api/mcp" } } } ``` ### Claude In Claude, go to **Customize > Connectors** and click **Add custom connector**. Enter the server URL and click **Add**. The Free plan allows one custom connector. On Team and Enterprise plans, an Owner adds the connector in **Organization settings > Connectors**, and each member then selects **Connect**. See the [Claude docs](https://claude.com/docs/connectors/custom/add-unlisted). ```text https://deference.si/api/mcp ``` ### Gemini CLI Add the server to `~/.gemini/settings.json`. The `httpUrl` key selects streamable HTTP, and `url` would select SSE. Then run `/mcp auth deference` in Gemini CLI. See the [Gemini CLI docs](https://geminicli.com/docs/tools/mcp-server/). ```json { "mcpServers": { "deference": { "httpUrl": "https://deference.si/api/mcp" } } } ``` ### OpenCode Add the server to `opencode.json`, then run `opencode mcp auth deference`. See the [OpenCode docs](https://opencode.ai/docs/mcp-servers/). ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "deference": { "type": "remote", "url": "https://deference.si/api/mcp" } } } ``` ### Zed Add the server to Zed's `settings.json`, or go to **Settings → AI → MCP Servers** and choose **Add Server**, then **Add Remote Server**. See the [Zed docs](https://zed.dev/docs/ai/mcp). ```json { "context_servers": { "deference": { "url": "https://deference.si/api/mcp" } } } ``` ### Cline Add the server to `cline_mcp_settings.json`. In the editor, open **MCP Servers**, then **Configure**, then **Configure MCP Servers**. Keep `"type": "streamableHttp"`, because without it Cline uses the older SSE transport. In the Cline CLI, run `cline mcp` and choose **Authorize OAuth**. See the [Cline docs](https://docs.cline.bot/mcp/connecting-to-a-remote-server). ```json { "mcpServers": { "deference": { "type": "streamableHttp", "url": "https://deference.si/api/mcp", "disabled": false, "autoApprove": [] } } } ``` ### Goose Add the extension to `~/.config/goose/config.yaml`. See the [Goose docs](https://goose-docs.ai/docs/getting-started/using-extensions). ```yaml extensions: deference: name: Deference type: streamable_http uri: https://deference.si/api/mcp enabled: true timeout: 300 ``` ### Any other client Add the server to the client's MCP settings with this URL. ```text https://deference.si/api/mcp ``` ## Sign in The consent page names the app, says whether Deference recognizes it, and lists what it can do. Read is always on. When the app asks for Write, it has its own switch. Write lets the app run models, generate images and manage its own API keys. Turn the switch off and this sign-in can only read. A read-only connection still lists every tool. Calling a Write tool returns HTTP 403 with an `insufficient_scope` challenge, asking the client to step up to Write. If the client does not open authorization, reconnect and allow Write. Other sign-ins of the same app keep what you allowed them. To take Write from an app that is already connected, disconnect it in [Agents](https://deference.si/agents) first. Authorize an app only if you started this connection yourself. You sign in once. After that the agent refreshes its own access, including in headless runs such as `claude -p` or CI on the same machine. A connection unused for 30 days asks you to sign in again, and so does every connection after 90 days. ## Spend budget Each connection spends through its own key, which Deference creates on the connection's first paid call and never shows to the agent. The budget starts at $10. Raise it, pause it or resume it in [Agents](https://deference.si/agents). Paid calls run a model or generate an image. Each one takes two inputs that keep its cost bounded: * `max_cost_usd` is the most the call may cost. The default is $0.50 and the highest is $5. When the worst case for the request is above it, the call is refused before anything is charged. * `idempotency_key` names the call. While its record is retained for 90 days, a completed retry with the same key and identical inputs never charges again. Every result states its cost and whether that cost is final or still provisional. Free credit pays for eligible text models. It never pays for images or web search. Text model outputs are never stored. A retry of a finished text call returns its receipt without the output. Generated images remain available for 24 hours. Before expiry, an image retry with the same idempotency key returns a fresh download link and no preview. The previous link stops working, and the expiry is unchanged. After expiry, the retry returns only the receipt. ## What your agent can do The agent reads the account's credit, free credit and this connection's budget, and sums spend by model, key or client over 24 hours to 90 days. It can look up any request by id, or list requests by key, model, status and time. It lists models by price, context length, output type and whether free credit can pay for them, compares up to 10 models side by side, and estimates a call's cost from token counts before it spends. With Write, it runs a text model on a prompt of up to about 64,000 characters, with optional web search, and gets the answer with its receipt. A model id ending in `:incognito` runs the call on confidential-computing hardware, and web search is refused on those ids. See [Incognito](https://deference.si/docs/incognito). An id ending in `:overdrive` pins the call to the model's one provider and refuses web search too. See [Overdrive](https://deference.si/docs/overdrive). It also generates images. The result shows a preview and links to the original file for 24 hours. With Write, it creates capped, expiring API keys for code that calls `/v1` itself, and rotates or revokes the keys it created. It reads every key on the account, masked. It searches these docs and reads any page as Markdown. [MCP tools](https://deference.si/docs/coding-tools/mcp-tools) lists every tool with its inputs. ## Prompts and docs The server offers three prompts. Claude Code lists them as slash commands, such as `/mcp__deference__pick_model`. * `setup_coding_tool` sets up Claude Code, Codex, Cursor or another tool with a new key. * `pick_model` finds models for a task within a budget and compares their cost. * `spend_report` summarizes what the account spent over 24 hours, 7 days or 30 days. Every docs page is also a resource: `deference://docs/` followed by the page's path, for example `deference://docs/quickstart`. In Claude Code, type `@` to attach one to your message. ## API keys over MCP An API key can connect too. Turn on **Allow MCP access** for the key in [API keys](https://deference.si/keys), then send the key as `Authorization: Bearer sk-df-...`. A key reads only. It never runs models, generates images or manages keys through MCP. ## Text from model providers Model descriptions come from providers. The tools return them, and docs text, in fields that end in `_untrusted`. Model output from `deference_run_model` comes back in `output_text`. All of this text is data, not instructions: your agent never acts on anything it says. ## Limits on agent keys A key an agent creates has a spend limit of $10 unless it asks for another. The spend limit is never more than $100. It expires after 30 days unless it asks for 7 or 90. Together, the keys agents create on your account can add at most $100 of spend limits in any 24 hours, even if they revoke and recreate keys. An account can have 10 active agent keys, and agents can make 20 key changes an hour. An app can rotate or turn off only the keys it created. A connection's spend key counts toward these limits. It is named `MCP spend` and then the app, and it expires after 90 days. The next paid call after that creates a new one. Agent keys are named after what the agent asked for, then the app, for instance `ci · Claude Code`. Raise a key's limit or remove it on [API keys](https://deference.si/keys). > **Rotate keys from shared transcripts** > > A new key appears in the agent's conversation. If you share or store that transcript, rotate the key. ## What stays with you An agent cannot buy or activate INFERENCE or add credit. When credit runs low, it asks you to [add credit](https://deference.si/overview). Raising a budget or a key's limit, deleting keys and disconnecting apps also stay in the dashboard. ## Disconnect Open [Agents](https://deference.si/agents), find the app and select **Disconnect**. The app loses access at its next request, and you can turn off the keys it created in the same step. To stop an app spending but keep it connected, pause its budget instead. Then remove the server from the client. **Claude Code** ```bash claude mcp remove deference ``` **Codex** ```bash codex mcp remove deference ``` To sign the client out but keep the server listed, run `claude mcp logout deference` or `codex mcp logout deference`. ## Troubleshooting | You see | Cause | Fix | | ---------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | `/mcp` shows **Needs authentication** | The client has not signed in yet, or its sign-in ended | Choose **Authenticate** | | `invalid_grant` after a long break | The sign-in went unused for 30 days, or is 90 days old | Sign in again | | A tool says **This connection can only read** | Write was off when the app was authorized | Reconnect and leave Write on | | A tool says **Key changes need an OAuth connection** | An API key asked to create, rotate or revoke a key | Use API keys, or connect through OAuth | | `insufficient_credit` | The account has too little credit, or only free credit for a call free credit cannot pay | [Add credit](https://deference.si/overview) | | `budget_exhausted` | The connection spent its budget | Raise the budget in [Agents](https://deference.si/agents) | | `spend_disabled` | You paused spending for the connection | Resume it in [Agents](https://deference.si/agents) | | `cost_cap_exceeded` | The call could cost more than its `max_cost_usd` | Raise `max_cost_usd`, lower `max_output_tokens` or pick a lower-priced model | | `idempotency_conflict` | The key was used for a different call | Use a new `idempotency_key` | | `still_running` | A call with the same key has not finished | Check `deference_list_requests` before you retry | | `rate_limited` | Too many requests at once | Wait and retry | | **Too many key changes** | More than 20 creates, rotations and revocations in an hour | Wait the minutes it names |