What an assistant can do

Read, simulate, propose.

  • Read

    Households, accounts, plans, history, progress, check-ins and cross-border rules. Money comes back in today's money unless you ask otherwise.

  • Simulate

    Projections, Monte Carlo, backtests, solvers, guardrails, tax breakdowns, explanations and the assumption audit, all read-only.

  • Propose

    Edits are change sets: a readable diff and a before-and-after result, applied only when you say so. Or a what-if branch that leaves the plan alone.

  • Two doors, one engine

    Every MCP tool has a REST twin. Use MCP for assistants and REST for scripts, webhooks and your own software.

  1. 1You ask

    “What if I retire three years earlier? Show me what it does to my chance of success.”

  2. 2Your assistant calls Glideworth's MCP tools

    • get_plan_summaryreads the plan
    • preview_changestries retiring at 57, stores nothing
    • run_monte_carlochance of success, before and after
    • propose_change_setwrites a proposal, applies nothing
  3. 3You review the proposal

    Change setProposed

    Retirement age
    60 57
    Chance of success
    86% 74%

    Illustrative figures

Tool names are real; figures are illustrative.

54 tools read and compute and are all marked read-only; 21 tools write and exist only when you switch writes on. More on the MCP server andthe REST API.

Safety model

An assistant can only do what its key allows.

  • Read-only by default

    The write tools do not exist until you set the server flag and the connecting key has write scope. A client cannot call a tool it cannot see.

  • Scoped keys and roles

    Keys carry read, simulate or write scope, and never more than their person's role allows. A viewer's connection has no write tools at all.

  • Change sets

    Each proposal is tied to the plan version it was written for. If the plan moved, the apply is refused and nothing is merged.

  • An audit trail

    Every apply is a plan version with the assistant's identity, and every write is in the audit log under the person whose key or consent it was.

  • No delete tool

    Anything destructive is a proposal. Reverting to an earlier version is a change set too, and history is append-only.

  • Hashed, shown-once secrets

    API keys, sessions and OAuth tokens are stored only as hashes. A key is shown once, when you create it.

What each key scope can reach
ScopeReads dataRuns simulationsProposes and applies edits
readYesYesNo
simulateNo (a calculator key)YesNo
writeYesYesYes, if the server has writes on
A worked session

“Can I spend 500 more a month on dining?”

One assistant, a read and write key, and writes switched on. Every call is a real tool from the MCP server; the numbers are illustrative.

  1. Orient

    The assistant reads the plan summary, the best first call, and notes the plan's version.

    MCP tool calls
    list_plans {}
    get_plan_summary { "planId": "plan-main" }
    # -> compact plan (ids and amounts like "5200 real/monthly"), outcome, 5-yearly table.
    #    The assistant notes plan version 4 and that dining lives in the expense exp-living.
  2. Ask "what if", storing nothing

    MCP tool calls
    preview_changes {
      "planId": "plan-main",
      "ops": [{ "op": "replace", "path": "/expenses/[id=exp-living]/amount/value", "value": 5700 }]
    }
    # -> { "planVersion": 4,
    #      "changes": ["Living expenses raised from 5,200 to 5,700 per month"],
    #      "preview": { "before": { "endNetWorthReal": 910000 }, "after": { "endNetWorthReal": 802000 } } }
    #    Nothing is stored.
  3. Propose it, still without applying anything

    The proposal is written against the version that was read.

    MCP tool calls
    propose_change_set {
      "planId": "plan-main",
      "baseVersion": 4,
      "summary": "Living expenses +500/month (dining)",
      "ops": [{ "op": "replace", "path": "/expenses/[id=exp-living]/amount/value", "value": 5700 }]
    }
    # -> { "id": "cs_9f2c1a", "status": "proposed", ... }   The plan is untouched.
  4. Show you, and wait

    The assistant tells you: "That takes about 108k off end net worth in today's money (910k to 802k), and the plan still never runs short. Want me to apply it?" Only when you say yes:

    MCP tool calls
    apply_change_set { "changeSetId": "cs_9f2c1a" }
    # -> { "status": "applied", "planId": "plan-main", "newVersion": 5 }
    
    # If you edited the plan in the app in the meantime:
    # -> { "error": { "code": "CHANGESET_CONFLICT", "details": { "baseVersion": 4, "currentVersion": 5 } } }
    #    Nothing is merged. The assistant re-reads, proposes again, and asks you again.
  5. Undo is also a proposal

    MCP tool calls
    list_plan_versions { "planId": "plan-main" }
    # -> version 5: by { kind: "mcp", label: "..." }, changeSetId "cs_9f2c1a"
    propose_revert { "planId": "plan-main", "version": 4 }   # review, then apply_change_set
    # History is append-only: the revert is version 6, holding version 4's content.

Other tasks use other tools: run_monte_carlo and explain_year for "why does it fail?",solve_max_spending for "the most I can spend at 90%", solve_retirement_date for "how early can I retire?", audit_plan for "find problems with my assumptions", andcompare_stay_or_move for "should we move abroad?".

Connect

Connect Claude or any MCP client.

Commands use the repository's scripts and the GLIDEWORTH_* variables. Create a least-privilege key first: read is enough for analysis. Use absolute paths in every config, and do not start a stdio server through pnpm run, which prints a banner into the protocol channel.

Claude Code, over HTTP

Terminal
# 1. Create a key that can only read and simulate (inside the repository)
pnpm keys:create -- --name claude --scopes read

# 2. Add the server to Claude Code over HTTP
claude mcp add --transport http glideworth http://localhost:8787/mcp \
  --header "Authorization: Bearer glideworth_ab12cd34_<rest of your key>"

Claude Code, over stdio

Terminal
# stdio: nothing else needs to run; the server reads the SQLite file directly (after pnpm build)
claude mcp add glideworth \
  -e GLIDEWORTH_DB_PATH=/abs/path/to/glideworth/apps/api/data/glideworth.db \
  -e GLIDEWORTH_MCP_ALLOW_WRITES=false \
  -- node /abs/path/to/glideworth/apps/api/dist/mcp/stdio.js

Claude Desktop

Edit claude_desktop_config.json and restart the app.

claude_desktop_config.json
{
  "mcpServers": {
    "glideworth": {
      "command": "node",
      "args": ["/abs/path/to/glideworth/apps/api/dist/mcp/stdio.js"],
      "env": {
        "GLIDEWORTH_DB_PATH": "/abs/path/to/glideworth/apps/api/data/glideworth.db",
        "GLIDEWORTH_MCP_ALLOW_WRITES": "false"
      }
    }
  }
}

If Glideworth runs in Docker, use the container's copy of the server instead:

claude_desktop_config.json (Docker)
{
  "mcpServers": {
    "glideworth": {
      "command": "docker",
      "args": ["exec", "-i", "-e", "GLIDEWORTH_MCP_ALLOW_WRITES=false", "glideworth", "node", "dist/mcp/stdio.js"]
    }
  }
}

Any other MCP client

Connection details
HTTP   URL      http://localhost:8787/mcp
       Header   Authorization: Bearer <key>
stdio  command  node apps/api/dist/mcp/stdio.js
       env      GLIDEWORTH_DB_PATH=/abs/path/to/glideworth.db

# Try it without any assistant:
npx @modelcontextprotocol/inspector

Step-by-step: Connect an AI assistant. To let an assistant propose edits, set GLIDEWORTH_MCP_ALLOW_WRITES=true on the server and use a key with write scope; leave both off otherwise.

Clients that connect to a server by URL, with no pasted key, sign in with OAuth 2.1 (PKCE, rotating refresh tokens, scopes capped by your role). The self-hosted server supports this behind your own HTTPS address when you setGLIDEWORTH_PUBLIC_URL. Bearer keys keep working.

REST API

The same operations as plain HTTP.

265 operations under /api/v1, described by an OpenAPI 3.1 document your tools can read.

Terminal
export GLIDEWORTH=http://localhost:8787 KEY=glideworth_ab12cd34_<rest of your key>

# Who am I, and what can this key do?
curl -s -H "Authorization: Bearer $KEY" $GLIDEWORTH/api/v1/me

# Deterministic projection, compact, in today's money
curl -s -X POST $GLIDEWORTH/api/v1/plans/plan-main/simulate \
  -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
  -d '{"view":{"basis":"real","fromYear":2030,"everyNYears":5,"series":["netWorth","taxes"]}}'

# Propose an edit (nothing is written), then apply it
curl -s -X POST $GLIDEWORTH/api/v1/plans/plan-main/change-sets \
  -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
  -d '{"summary":"Raise travel to 15k","baseVersion":4,"ops":[{"op":"replace","path":"/expenses/[id=exp-travel]/amount/value","value":15000}]}'
curl -s -X POST $GLIDEWORTH/api/v1/change-sets/<id>/apply -H "Authorization: Bearer $KEY"
  • The OpenAPI document is served by every running server at /openapi.json, generated from the same schemas as the engine, and an interactive reference is at /docs. The same document is listed by tag, method and path in the API reference on this site. That reference page loads its viewer script from a public CDN, so it needs internet access; the document and every API call work offline. Generate a typed client with a standard tool such as openapi-typescript.
  • Idempotency. Send an Idempotency-Key header on any write; a retry within 24 hours replays the first response. Using a key for a different request is an error.
  • Concurrency. Plans and households have an ETag version. Send If-Match and a stale write is a 409, not an overwrite.
  • Long jobs (Monte Carlo, solvers) return a job. Add ?wait=60 to block, or poll, or stream progress as server-sent events.
  • Webhooks deliver signed events (plan updated, simulation completed, snapshot created, check-in completed, notification created). Each carries an HMAC-SHA256 signature over a timestamp and the body, with retries, and the server refuses to deliver to private network addresses unless you allow it.
  • Limits. 600 requests a minute per key and a 10 MiB request body by default, both configurable on your own server.
Hosted endpoint

A stable address, planned.

Self-hosting an MCP server for a chat app that connects by URL means putting it behind HTTPS on an address that app can reach, or running a tunnel. For the hosted service, the plan is a stable HTTPS address with OAuth sign-in, so that Claude and other MCP clients can connect without either. It would also bring fair-use limits on server-side simulation jobs, and the MCP write tools would stay off for a new workspace until the owner turns them on.

The API and the MCP tools themselves are the same code in both places. See pricing for the plan, and security for what is built and what is planned.

Questions

Questions about assistants and your data.

Can an assistant change my plan without asking me?

Not through plan edits. Edits are change sets: the assistant proposes them, you see the readable diff and the before-and-after result, and only an explicit apply changes the plan. Applying is refused if the plan changed after the proposal. A few tools write household data directly (balances, progress snapshots, imports), and they exist only when you have switched writes on and given the key write scope.

Can an assistant delete my data?

No. There are no delete tools. Even reverting to an earlier plan version is a proposal you approve, and history is append-only.

Does Glideworth send my plan to an AI provider?

No. Glideworth has no AI in it and sends nothing anywhere. An assistant you connect sees what its tools return, within its key’s scopes, and the provider of that assistant sees it too. Use a local model if that matters.

Which assistants work?

Any client that speaks the Model Context Protocol over Streamable HTTP or stdio. The documentation covers Claude Code and Claude Desktop; the connection details for other clients are the same URL and header, or the same command.

Is the hosted endpoint available?

Not yet. The hosted service is about to open, and a stable HTTPS address with OAuth sign-in is part of its plan. Today the MCP server runs on your own machine or server.

Try it on a sample household.

Free to self-host today, with every feature. The hosted service opens later, at $9 a month or $90 a year.