---

The MCP server lets external AI agents talk to your portfolio over the Model Context Protocol. Point Claude Desktop, Claude Code, Cursor, Windsurf, Cline, or any MCP-capable client at Wealthfolio and it can read your holdings, performance, and activities — and, if you allow it, draft or record new activities — through the exact same typed tools the built-in AI Assistant uses.

Every connection is authenticated with a scoped access token you create and can revoke. Nothing is exposed until you turn the server on and hand out a token.

---

1 · Where it lives

Open Settings → AI Agent Access. What you see depends on how you run Wealthfolio:

• Desktop app — a master toggle turns the feature on, then a local MCP server runs at http://127.0.0.1:<port>/mcp. You control it with Start/Stop, choose whether it starts with the app, and toggle audit logging.
• Self-hosted / web server — the endpoint is enabled with an environment variable (see §6) and served at /mcp on the same origin as your server. Token management and the audit log work the same way.

---

2 · Turn it on and create a token

1. Enable the server. Flip the master toggle (desktop) or set the environment variable (self-hosted). On desktop, press Start — the endpoint URL appears with a green dot when it’s live.
2. Create an access token. Under Personal access tokens, click Create token, name it (e.g. “Claude Desktop”), pick an expiry, and choose its scopes. Tokens default to read-only — one click away from the common case.
3. Copy the token once. It’s shown a single time at creation. The dialog also gives you a ready-to-paste client config with the token already embedded.

Expiry options are 7 days, 30 days, 90 days (default), 1 year, or no expiry. Shorter is safer — you can always mint a new one.

---

3 · Scopes — what a token can do

A token carries a set of scopes. The agent can only call tools its scopes allow; the backend rejects anything outside them. Scopes split into read and write.

Read access

Write access

The dialog offers four presets that cover most needs: Read-only, Read + draft, Read + write, and Read + write + suggest. Activities — commit/write always pulls in Activities — draft automatically — an agent has to be able to stage a change before it can commit one.

---

4 · Connect a client

Wealthfolio speaks Streamable HTTP MCP. Most clients (Claude Desktop, Claude Code, Cursor, Windsurf, Cline) share the same config shape — the Copy config button on the server card produces exactly this, with YOUR_TOKEN as a placeholder:

{
  "mcpServers": {
    "wealthfolio": {
      "type": "http",
      "url": "http://127.0.0.1:PORT/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

Replace PORT with the port shown on the server card (self-hosted users use their server’s URL) and YOUR_TOKEN with the token you copied.

VS Code differs — it uses a top-level servers key:

{
  "servers": {
    "wealthfolio": {
      "type": "http",
      "url": "http://127.0.0.1:PORT/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

Any other client that speaks Streamable HTTP just needs the URL plus an Authorization: Bearer YOUR_TOKEN header.

Where the config goes

Once connected, the agent discovers Wealthfolio’s tools automatically. Ask it “what are my top holdings?” or “how did my portfolio do this year?” and it’ll call the read tools and answer with your real numbers.

---

5 · Audit log

Every tool call an agent makes is recorded under Agent activity — the time, the tool name, the outcome (Success, Denied, or Error), and which token made the call. Filter by tool or outcome, search, and Clear log when you want a clean slate.

On desktop, the Log agent activity switch turns recording on or off. On a self-hosted server it’s controlled by an environment variable (below). With logging off, no new audit rows are written.

---

6 · Self-hosted servers

On a self-hosted Wealthfolio server the MCP endpoint is off by default and enabled with environment variables:

After enabling, create tokens from Settings → AI Agent Access exactly as on desktop. The url in your client config is your server’s origin plus /mcp (for example https://wealth.example.com/mcp).

---

7 · Security model

• Nothing is exposed by default. The server is off until you enable it, and it serves nothing without a valid token.
• Local-only on desktop. The desktop server binds to 127.0.0.1 — it isn’t reachable from other machines on your network.
• Scoped and revocable. Each token carries only the scopes you granted. Remove a token and any client using it loses access immediately.
• Writes are gated. Committing an activity requires both the draft and write scopes; a draft-only token can stage changes but never commit them.
• Stopping ≠ revoking. Stopping the server (or disabling the feature on desktop) keeps your tokens valid — they resume working when you start it again. To cut a client off for good, delete its token.
• Typed tools, not raw SQL. Agents call the same scoped, typed tools as the AI Assistant. They never receive your database or your other API keys.

---

8 · Troubleshooting

The client can’t connect

• Make sure the server is running (green dot on the server card, or WF_MCP_ENABLED=true and a restart on self-hosted).
• Check the url and PORT match what’s on the server card, and that the path ends in /mcp.
• Confirm the Authorization header is Bearer <token> with a valid, unexpired token.

The container won’t start after setting WF_MCP_ENABLED=true

On self-hosted installs that bind to the network, MCP requires Wealthfolio auth. If you set WF_AUTH_REQUIRED=false and rely only on a reverse proxy for login, the server refuses to start because the Agent Access API can mint long-lived MCP tokens.

Fix it by configuring WF_AUTH_PASSWORD_HASH or OIDC, then restart with WF_MCP_ENABLED=true. If you don’t want Wealthfolio auth enabled, leave WF_MCP_ENABLED=false.

The agent says a tool was “denied”

The token is missing the scope for that tool. Create a new token with the scope you need (or the right preset) — scopes can’t be edited after creation, so mint a fresh one and remove the old.

It worked yesterday, not today

Check whether the token expired (see its status in the token list) or was removed. On desktop, also confirm the server is started and, if you rely on it, that auto-start is on.

---

Next step: If you’d rather chat with your portfolio from inside the app instead of wiring up an external agent, see the AI Assistant.

---