# Savi MCP server

Connect AI assistants to Savi Finance with the hosted Model Context Protocol (MCP) server: endpoint, sign-in flow and available tools.

Last updated October 2, 2026

The Savi MCP server is a remote [Model Context Protocol](https://modelcontextprotocol.io) server. It lets an AI assistant read and manage your Savi accounts, transactions, goals, categories, tags and more, using the same data as the Savi apps.

## Server URL

```text
https://mcp.financesavi.com/mcp
```

Add this URL as a custom or remote MCP server in your client. Clients that implement the MCP authorization spec need no other configuration: they discover the authorization server, register themselves and open a browser window for you to sign in. See [Authentication](https://financesavi.com/developers/authentication) for the full flow.

## Connect a client

Choose your client to open its available one-click connection or generate a configuration. Savi handles sign-in through OAuth; you do not need to create or paste a token.

Setup commands and configuration for all clients

### Claude Code

```bash
claude mcp add --transport http savi https://mcp.financesavi.com/mcp
```

### Gemini CLI

```bash
gemini mcp add --scope user --transport http savi https://mcp.financesavi.com/mcp
# Then inside Gemini CLI, sign in through Savi:
#   /mcp auth savi
```

### ChatGPT

```text
Settings → Connectors → Advanced → Developer mode, then Create:
Name:       Savi
Server URL: https://mcp.financesavi.com/mcp
Auth:       OAuth
```

### Cursor

```json
{
  "mcpServers": {
    "savi": {
      "url": "https://mcp.financesavi.com/mcp"
    }
  }
}
```

### VS Code

```json
{
  "servers": {
    "savi": {
      "type": "http",
      "url": "https://mcp.financesavi.com/mcp"
    }
  }
}
```

### Claude Desktop bridge

```json
{
  "mcpServers": {
    "savi": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.financesavi.com/mcp"
      ]
    }
  }
}
```

### MCP Inspector

```bash
npx @modelcontextprotocol/inspector --server-url https://mcp.financesavi.com/mcp --transport http
# Open the authenticated local URL printed by Inspector, then complete OAuth.
```

### Other clients

```text
Server URL: https://mcp.financesavi.com/mcp
Transport:  Streamable HTTP
Auth:       OAuth 2.1 with PKCE (discovered automatically)
```

Cursor uses `.cursor/mcp.json`; VS Code uses `.vscode/mcp.json`. The Claude Desktop JSON option uses `claude_desktop_config.json` with the third-party [mcp-remote bridge](https://github.com/geelen/mcp-remote) and requires Node.js. The Add to Claude button opens a pre-filled remote connector form. ChatGPT connects through a custom connector in Settings → Connectors with Developer mode on. Gemini CLI uses `~/.gemini/settings.json` with the `httpUrl` key, then `/mcp auth` to sign in through Savi.

To install in Cursor, choose Cursor in the connection generator and select _Open in Cursor_. Cursor asks you to confirm the Savi MCP server; after installation, connect and complete Savi sign-in in your browser. For manual setup, add the generated server entry to a project`.cursor/mcp.json` or your personal `~/.cursor/mcp.json`. See the [Cursor MCP guide](https://cursor.com/docs/mcp) for details.

1.  The client discovers Savi's authorization server and registers itself.
2.  Your browser opens a Savi page. Sign in with your email and the 6-digit code.
3.  Review what the app is asking for and approve it. Untick _Allow changes_ to give read-only access.
4.  You are returned to the client, which can now call the tools below.

## Verify your first read-only call

1.  **Confirm the connection.** Return to the client after consent. Start or reconnect the Savi server and inspect its discovered tools. Seeing a sign-in page alone does not verify the connection.
2.  **Check your identity.** Call [`get_current_user_info`](https://financesavi.com/developers/mcp/tools/get_current_user_info) with no arguments. A successful result confirms that the client can act as the signed-in user.
3.  **Read your accounts.** Call [`list_accounts`](https://financesavi.com/developers/mcp/tools/list_accounts) with no arguments. An empty list is a valid result when you have no accounts. Use IDs returned by this call for later account operations.
4.  **Inspect the result.** Check for a top-level JSON-RPC error, then `result.isError`. The local playground checks input and envelope shapes; only a call from your connected client verifies real access.

```text
Use Savi get_current_user_info to confirm which user is signed in, then list_accounts to summarize my accounts. Make read-only calls only; do not create, update, or delete anything. If a call fails, explain the error instead of inventing data.
```

In VS Code, use _MCP: List Servers_ to inspect the server and select its tools in chat. Client trust and individual tool approvals are separate from Savi's OAuth consent; keep each approval visible while exploring.

## Verify with MCP Inspector

For a client-independent walkthrough, install Node.js 22.19 or newer and launch the official [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector):

```bash
npx @modelcontextprotocol/inspector --server-url https://mcp.financesavi.com/mcp --transport http
```

Open the authenticated local URL printed in the terminal. Complete OAuth using the email-code and consent pages, then inspect the tools and run the two read-only calls above. Use the protocol and network views to distinguish an HTTP failure from a tool error. Keep Inspector's local session token private.

## Connection troubleshooting

| What you see | What to do |
| --- | --- |
| 401 before sign-in | This starts OAuth discovery. Let the client follow the `WWW-Authenticate` metadata URL. An API email-code token cannot replace an MCP OAuth token. |
| Sign-in succeeds but no tools appear | Return to the client, reconnect or start the server, and enable Savi tools. Check host trust and tool selection. Use Inspector to isolate client setup from the Savi connection. |
| Consent was denied or the callback failed | Restart authorization in the client. For a custom OAuth client, match the registered redirect URI exactly and use the same PKCE verifier. Do not reuse a single-use authorization code. |
| A write reports insufficient scope | A read-only grant cannot write. Reauthorize only if you intend to allow changes, then review the requested permissions. Retrying the same call does not add scope. |
| A session request returns 404 | Start a new initialization handshake without the old session ID. Let your MCP SDK manage the new session. |
| A tool returns `isError: true` | Read its content and verify the arguments, ownership, and current IDs. Check whether a write completed before retrying after a timeout. |

## Endpoints

All endpoints are served from `https://mcp.financesavi.com`.

| Path | Method | Purpose |
| --- | --- | --- |
| `/mcp` | POST, GET, DELETE | MCP streamable HTTP transport. Requires a bearer token. |
| `/.well-known/oauth-protected-resource` | GET | Protected resource metadata (RFC 9728). |
| `/.well-known/oauth-authorization-server` | GET | Authorization server metadata (RFC 8414). |
| `/register` | POST | Dynamic client registration (RFC 7591). |
| `/authorize` | GET | Start sign-in in a browser. |
| `/token` | POST | Exchange an authorization code or a refresh token for tokens. |
| `/revoke` | POST | Revoke an access or refresh token (RFC 7009). |

## Tools

The server exposes 71 tools. Tools act as the signed-in user, so none takes a user ID. Browse the [complete tool reference](https://financesavi.com/developers/mcp/tools).

## Test clocks for time-based flows

Test clocks create isolated transaction feeds and goal timelines for integration tests. They let an agent exercise scheduled activity without waiting for real bank posts or changing the user's financial records. Start with [create\_test\_clock](https://financesavi.com/developers/mcp/tools/create_test_clock), then use its returned `clock.id` with [advance\_test\_clock](https://financesavi.com/developers/mcp/tools/advance_test_clock) and [read\_test\_clock](https://financesavi.com/developers/mcp/tools/read_test_clock).

```json
{
  "frozenTime": "2026-10-02T00:00:00Z",
  "transactions": [
    {
      "at": "2026-10-03T00:00:00Z",
      "name": "Simulated payroll",
      "amount": 2500,
      "currency": "CAD",
      "type": "INCOME"
    }
  ],
  "goals": [
    {
      "name": "Emergency fund",
      "targetAmount": 1000,
      "initialAmount": 100,
      "contributions": [
        {
          "at": "2026-10-03T00:00:00Z",
          "amount": 150
        },
        {
          "at": "2026-10-04T00:00:00Z",
          "amount": 250
        }
      ]
    }
  ]
}
```

The clock exposes due transactions and contributions as posted, with later events listed as pending. Read them through these test-clock tools; they do not appear in the ordinary transaction or goal lists. Its schedule is immutable after creation, simulated time cannot move backwards, and the maximum time is returned as `maxTime`. Clocks expire after seven days; use [delete\_test\_clock](https://financesavi.com/developers/mcp/tools/delete_test_clock) to clean up sooner. Creating, advancing, and deleting require the `write` scope; reading requires `read`.

## Read-only and write access

Every tool is either read-only or changes data. Tokens carry the `read` scope, the `write` scope, or both, and a tool call without the required scope is rejected. When you approve a connection you can untick _Allow changes_ to give an assistant read-only access. Each tool also advertises MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) so clients can warn before deleting anything. The [tool reference](https://financesavi.com/developers/mcp/tools) lists the effect and scope of each tool.

## Session lifecycle

1.  Complete OAuth sign-in and send `initialize` to negotiate the protocol version and capabilities.
2.  Send `notifications/initialized`, then discover tools with `tools/list`.
3.  Invoke a tool with `tools/call`. Include the negotiated protocol version and the server-issued `Mcp-Session-Id` on subsequent HTTP requests. Send `Accept: application/json, text/event-stream` and handle both JSON and SSE responses.
4.  Keep session handling in your MCP SDK or host client. A raw tool frame alone does not establish a session.

Protocol negotiation comes from the server's initialization response. These frames describe Savi's current session-based transport; copying a newer specification's sessionless flow does not change the deployed server.

## User confirmations and sensitive input

When implementing an MCP server workflow that needs explicit user confirmation before a consequential action, request it with [MCP elicitation](https://modelcontextprotocol.io/specification/2026-07-28/client/elicitation). Clients should proceed only when the response action is `accept`; `decline` and `cancel` are not approval. In protocol version `2026-07-28`, elicitation is delivered through [multi-round-trip requests](https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/mrtr), not the legacy server-initiated request flow.

Never ask users to enter passwords, API keys, access tokens, or payment credentials in a free-text message or form-mode elicitation. Use URL-mode elicitation to send them to a trusted HTTPS flow where the credentials go directly to your service and stay out of the MCP client and model context. Do not put secrets in the URL.

MCP Sampling was deprecated in protocol version `2026-07-28` (July 28, 2026). New implementations should not adopt it; if your server needs model generation, integrate directly with the model provider API. See the official [Sampling guidance](https://modelcontextprotocol.io/specification/2026-07-28/client/sampling).

## Protocol errors and tool errors

A protocol failure returns a top-level JSON-RPC `error` object. A tool operation can instead return a `result` with `isError: true`. Check both layers before consuming `content`; valid JSON and a successful HTTP exchange do not prove that the operation succeeded.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid tool arguments"
  }
}
```

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "content": [
      {
        "type": "text",
        "text": "The operation could not be completed."
      }
    ]
  }
}
```

Each tool reference includes a local playground for inspecting these envelopes and validating arguments. The examples simulate protocol shapes; they do not access your data.

## Resources and prompts

The [public tool manifest](https://financesavi.com/developers/contracts/mcp-tools.json) includes every tool's complete nested input schema, annotations, and scope. Each tool page also includes its full JSON Schema in raw Markdown and copied agent prompts.

Savi currently registers tools only. It does not advertise MCP resources, resource templates, resource subscriptions, or server prompt templates. The natural-language examples below are tasks you give your assistant, rather than entries returned by `prompts/list`. Use the tool reference for supported capabilities.

## Rate limit

Each signed-in user can make up to 300 MCP requests per minute. Beyond that the server answers `429` with a `Retry-After` header.

## Example prompts

*   “Where did my household spending change this month?”
*   “List my last 20 transactions over $100.”
*   “Create a savings goal for a $3,000 vacation.”

Source: https://financesavi.com/developers/mcp