> For the complete documentation index, see [llms.txt](https://etherfi.gitbook.io/etherfi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://etherfi.gitbook.io/etherfi/products/cash/mcp-server.md). # MCP Server Connect an AI assistant to your ether.fi Cash account. Read-only, scope by scope, approved with your passkey. {% hint style="warning" %} **Coming soon.** The ether.fi Cash MCP server is not yet available to the public. This page describes the connector ahead of its release. {% endhint %} ether.fi Cash exposes an [MCP](https://modelcontextprotocol.io) server that lets an AI assistant read your account: your transactions, your cards, your balances and holdings. Ask Claude or ChatGPT what you spent on groceries last month, or what your spending power is today. The connector URL is: ``` https://mcp.ether.fi/mcp ``` The connector is read-only. There is no write path anywhere in the system, so no assistant can spend, borrow, repay, withdraw, or change your cards through it. Supported assistants are limited to a registry ether.fi maintains. Today that is Anthropic (Claude, including Claude Code) and OpenAI (ChatGPT). *** ## 1. Connecting an assistant Open **Settings → AI Connections** in the Cash app to copy the connector URL and manage your connections. 1. **Copy the URL.** One connector covers every Cash account you hold. 2. **Add it in your assistant.** Open its settings and look for connectors, apps, or plugins, then add one by URL and paste. 3. **Approve with your passkey.** You return to the Cash app to pick an account and choose what the assistant can read. {% hint style="info" %} A passkey is required. If your account has no passkey yet, add one in your security settings, then start the connection again from your assistant. {% endhint %} *** ## 2. What an assistant can read Access is split into three scopes. All three default to off, and you choose which to grant when you approve. | Scope | What you approve | Assistant can read | | ------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | | `transactions:read` | Your transactions and merchants | Card purchases and on-chain activity: merchant, amount, date, category. Includes top-ups, withdrawals, borrows, repayments, and cashback. | | `cards:read` | Your cards | Card nickname, network, and last four digits. Never the full number, CVC, or expiry. | | `balances:read` | Your balances, holdings, and vault address | Available balance, credit limit, amount borrowed, and the assets in your vault with quantity and dollar value. Includes your vault address. | {% hint style="warning" %} Your vault address is a permanent public identifier. Anyone holding it can look up all of the account's on-chain activity, including after you revoke the connection. {% endhint %} Five tools sit behind those scopes. A tool only exists for an assistant whose grant carries the matching scope. | Tool | Scope | Reads | | --------------------- | ------------------- | ---------------------------------------------------------------------------- | | `list_transactions` | `transactions:read` | Card and on-chain activity, filterable by date, category, and merchant | | `list_cards` | `cards:read` | Nickname, type, last four digits, status, currency | | `get_main_account` | `balances:read` | Spending power, credit limit, amount borrowed, vault address | | `get_portfolio` | `balances:read` | Per-asset holdings: quantity, dollar value, whether it backs spending, yield | | `get_deposit_address` | `balances:read` | Deposit address and the networks and assets it accepts | *** ## 3. What an assistant cannot do Four boundaries hold at every scope, for every assistant. **No writes.** No spending, borrowing, repaying, withdrawing, or card management. A write scope would be a different threat model, so none exists. **No card secrets.** The full card number, CVC, and expiry are not readable through the connector at any scope. `list_cards` returns the same fields the app's card list shows without stepping up authentication. **No choosing an account.** The account is never a tool parameter. It lives inside the signed token issued for the connection and is re-derived on every request. One connection reads exactly one account, and an assistant cannot ask for a different one. **No figures ether.fi did not compute.** There is no spending-total tool. Every number the connector returns is one your own app screen also shows, so anything an assistant quotes can be checked against a row you can open. Totals are the assistant's arithmetic over transactions you can see. {% hint style="info" %} AI assistants can make mistakes when summarising or totalling. Treat what an assistant tells you as a convenience and your Cash app as the source of truth. {% endhint %} *** ## 4. Consent Every connection is approved on an ether.fi screen, in your browser, with a passkey. On it you: * **Pick the account.** If you hold more than one, they are labelled distinctly. * **Choose the scopes.** Switches default to off. Granting nothing is a valid outcome. * **See existing connections.** If that assistant is already connected to that account, approving adds a second connection rather than replacing the first. * **Prove presence with a passkey.** That signature binds the grant to you and to the account you picked. Everything the screen says about who is asking comes from ether.fi's own registry: name, icon, developer, and verified legal entity are all fields ether.fi controls. None of it comes from what the client asserts about itself, because a name a client picks is a name an attacker can pick. This is what makes consent phishing survivable, and it is why the screen also shows where you will be returned to. One grant covers one assistant on one account. Connecting the same assistant to a second account creates a second grant with its own scopes. *** ## 5. Lifetime and revocation A grant lives for 90 days. Within that window the assistant holds a one-hour access token and quietly renews it, so you are not asked to re-approve hourly. Connections are listed under **Settings → AI Connections** with the account each one reads, the scopes it holds, and when it expires. **Disconnect** sits on every connection behind one confirmation, and takes effect on the assistant's next request. Access is re-checked on every read, so revocation never waits for a token to expire. You only re-approve when a grant hits its 90-day expiry or you disconnect it. *** ## 6. How it works ``` Claude / ChatGPT mcp.ether.fi ether.fi Cash backend (MCP client) (MCP server + (authorization server + OAuth 2.1 facade) account data) | | | | 1. connect, no token | | |----------------------------->| 401, plus which scopes exist | | | | | 2. authorize + PKCE --------|------------------------------->| | | consent in your browser: | | who is asking, which account, | | which scopes, passkey |<------ one-time code --------|--------------------------------| | 3. exchange code -----------|------------------------------->| |<------ access token (1h) + refresh token (90d) --------------| | | | | 4. tool call, with token | | |----------------------------->| verify the token | | |------- internal read --------->| | | is the grant still alive? | | does its scope allow this read? |<----- data for that one account -----------------------------| ``` Two things about that split are worth naming. The connector never mints tokens: it serves the MCP transport and forwards the OAuth endpoints, while the Cash backend is the authorization server and signs tokens with keys held in a KMS. And account reads never cross the public internet, because the routes the connector calls are reachable only from inside ether.fi's own network. *** ## Further reading * [Technical Documentation](/etherfi/products/cash/technical-documentation.md), how Cash accounts, vaults, and settlement work * [🔒 Vault](/etherfi/products/cash/vault.md), the non-custodial key and ownership model behind your account * [Model Context Protocol](https://modelcontextprotocol.io), the open standard the connector implements --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://etherfi.gitbook.io/etherfi/products/cash/mcp-server.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.