Connect a client

One URL, and your browser does the signing in.

https://mcp.walletguide.com

Connectors set up with the earlier address, https://api.walletguide.com/mcp, keep working as they are, with no need to reconnect.

Add it as a remote MCP server in whatever client you use. It will discover the authorization server, register itself, and open a browser for you to approve. Nothing to install, no key to store, and you can withdraw the grant later without touching the client.

In the app, the robot icon at the bottom of the sidebar shows the address with a copy button, and User settings → Connect AI has step-by-step setup for ChatGPT, Claude, Claude Code, Cursor and other clients. The same steps, for people who have no account yet, are at walletguide.com/agents#connect, and an agent asked to set Walletguide up follows walletguide.com/agents.md.

Claude CodeCopy Anchor Link

claude mcp add --scope user --transport http walletguide https://mcp.walletguide.com

--scope user adds it for every project. In a new session, Claude gives you a sign-in link the first time it uses Walletguide; without one, type /mcp, pick walletguide and sign in.

With an API key insteadCopy Anchor Link

Some clients cannot open a browser — a server, a container, a CI job. The same URL takes a wg_ key as a bearer token:

claude mcp add --transport http walletguide https://mcp.walletguide.com \
  --header "Authorization: Bearer wg_…"

The key is scoped to one wallet, so tools default to it and walletId is optional. It carries its own permissions rather than scopes, and the connection sees the tools they allow: a viewer key the read tools, an editor key the data writes too, and wallet settings and bank connections only when the key's permission list names wallet:manage or integrations:manage. A key cannot create wallets or ask for access requests; both need a person's consent over OAuth.

Sign inCopy Anchor Link

Clients sign in when they connect. The first request without a token answers HTTP 401 with a WWW-Authenticate header pointing at the resource_metadata URL, and the client starts sign-in from there. The metadata lists every scope, and a client that asks for what it lists gets a consent screen with every option. In Claude Code the server shows as needing authentication, and the model gets an authenticate tool for it, which returns a sign-in link to hand to you.

Signed in, a connection lists only the tools its token's scopes allow. If a client calls one the token does not cover anyway, the answer is HTTP 403 with error="insufficient_scope" and a scope listing everything the token holds plus what is missing (for a batch, what all of its calls are missing), so a client that supports step-up can ask you to sign in again with that option ticked. One that does not reports the 403; disconnecting and connecting again with the option ticked does the same. A 403 inside a tool result, without insufficient_scope, is your role in the wallet saying no, and signing in again will not change it. The API checks the token's scopes again on every call.

https://api.walletguide.com/mcp asks for sign-in and steps up the same way.

What you are approvingCopy Anchor Link

Before the consent screen opens, the person signs in. Someone without an account creates one on that page and confirms their email address; the consent screen waits for the confirmation and continues by itself.

The client identifies itself as well. Claude, ChatGPT and VS Code do it with a Client ID Metadata Document, an HTTPS client_id that serves the client's own metadata, so they need no registration; other clients register themselves through dynamic client registration. Either way the consent screen names the app asking.

It lists the scopes the client asked for. Two matter:

• walletguide:read reads everything in the wallets you can reach
• walletguide:write creates, changes and deletes

Read is always included. Write is a checkbox, Add and change data in your wallets, and for an existing account it starts unticked: click straight through and you get a read-only session, with the mutating tools absent rather than present and refused. For an agent you are pointing at your own finances to answer questions, that is the setting you want. Tick it only when you want the agent to categorize, edit or clean up for you. An account created in the last day (someone who signed up to connect this client) finds every option it asked for ticked instead, and can untick them.

A client may also ask for two opt-in scopes. Both appear only when the client names them, both start unticked for an existing account (ticked for one created in the last day, like write), and the tools they open stay out of the catalogue until you tick them:

• Change wallet settings and manage bank connections (walletguide:admin): wallets_patch and the image tools, integrations_connect_link and integrations_sync, the access_requests_* tools, and invitations_list and api_keys_list to name what a request is about (only where your own role manages members or keys; a key's secret is never listed). It adds no data writes, and never changes members, invitations, API keys or a wallet's existence directly.
• Create wallets for you (walletguide:create_wallets): wallets_create, for wallets with you as the owner, sample wallets included.

Whatever is ticked, your role in each wallet still bounds what the agent can do there. A client that wants everything an agent needs to set a wallet up asks for walletguide:read walletguide:write walletguide:admin walletguide:create_wallets.

To change your answer later, disconnect the app and connect again. Every app you connected over OAuth is listed under User settings → Connected apps, and disconnecting there takes effect immediately.

How it works underneathCopy Anchor Link

The endpoint speaks streamable HTTP in both protocol eras: the 2025 revisions with their initialize handshake, and 2026-07-28 with server/discover. A client negotiates whichever it supports, and the catalog is the same either way. It builds a fresh server per request rather than holding session state, and refuses subscriptions/listen, since the catalog never changes within a connection. A tool call is dispatched back through the real REST route in-process, so it gets exactly the validation and the authorisation an external caller gets. There is no faster path around the checks, deliberately.

The token is minted for the address the client connected to as its audience: https://mcp.walletguide.com (a client may send it with a trailing slash, or as https://mcp.walletguide.com/mcp), or https://api.walletguide.com/mcp for a connection made with the earlier address. Any of them works on every MCP address, and the REST routes refuse all of them. So a client that holds an MCP grant cannot turn round and use it against /wallets/*, even though the same person approved the same application. See authentication.

Which walletCopy Anchor Link

An OAuth grant can reach several, so tools take a walletId. Call wallets_list first, or tell the agent which one to use.

Setting a wallet upCopy Anchor Link

The server's instructions walk an agent through this, and get_started tells it where it stands: how it is connected, which consent options the person did not tick, and the tools each would add. An agent missing a tool calls it, then asks the person to disconnect and connect again with the option ticked.

1. Find or create the wallet. wallets_list; with none, wallets_create takes a name, a base currency and an idempotencyKey, so a retried call returns the wallet it already made instead of a second one. type: "sample" with addSampleData makes a sample wallet with example data, deleted after 14 days. The answer carries url, the wallet in the app, to hand to the person. The person's first wallet starts their free trial, as in the app. Without walletguide:create_wallets the call answers 403 with url set to the page where the person creates the wallet themselves.
2. Connect the banks. integrations_connect_link returns a link into the app's bank dialog, where the person picks their bank and signs in with it; with an assetId it opens the reconnect dialog for a connection in error or expired. The agent never sees a bank credential. integrations_sync refreshes connected banks now, skipping any already queued.
3. Fill in the rest. assets_create and transactions_bulk for what no bank knows about. Importing a bank's CSV export stays in the app.
4. Do the setup work with the write tools, and answer from the data_* tools.

Access requestsCopy Anchor Link

Inviting someone, changing or removing a member, withdrawing an invitation, creating or revoking an API key and deleting a wallet are never done by an agent. With walletguide:admin it can ask: access_requests_invite, access_requests_change_role, access_requests_remove_member, access_requests_revoke_invitation, access_requests_create_api_key, access_requests_revoke_api_key and access_requests_delete_wallet each store the exact change and return an approvalUrl. The ids to withdraw or revoke come from invitations_list and api_keys_list. The person opens it in Walletguide, signed in as themselves (nobody else sees the request), and approves or declines. Then access_requests_get reads succeeded, failed (with the reason) or rejected.

• Nothing changes when the agent asks. Approval checks everything again: the person must still hold the permission (only the owner can approve deleting a wallet, by typing its name), the app must still be connected with walletguide:admin, and a member the request is about must be as they were. An invitation or key already gone by then fails the request.
• A request runs once, however many times it is approved.
• A request expires after an hour unanswered, and at most 10 wait per person and wallet.
• A new API key's secret is shown once, to the person in the browser, and never returned to the agent.

StandardsCopy Anchor Link

RFC 8414 and RFC 9728 for discovery, RFC 8707 for the resource indicator, PKCE on every flow, and dynamic client registration so a client can register itself. If your client implements the MCP authorization spec, it will work without configuration.

The authorization server is https://api.walletguide.com/auth, and its metadata is at https://api.walletguide.com/.well-known/oauth-authorization-server/auth. The protected-resource document on the host the client connected to names it: https://mcp.walletguide.com/.well-known/oauth-protected-resource, or https://api.walletguide.com/.well-known/oauth-protected-resource/mcp for the earlier address.

Before connecting, a client can read what the server is from its SEP-2127 Server Card at https://mcp.walletguide.com/server-card, found from the domain through walletguide.com/.well-known/ai-catalog.json. Every MCP address serves its own card under /server-card, https://api.walletguide.com/mcp/server-card among them. A card in the MCP Registry's server.json shape is at https://api.walletguide.com/.well-known/mcp.