Connect an AI assistant over MCP
Connect Claude Code, Claude Desktop, Cursor and other MCP clients to Glideworth over HTTP or stdio with a least-privilege key, and keep plan edits as proposals you approve.
Glideworth’s MCP server has 75 tools: 54 that read and compute, and 21 that write, which are off unless you turn them on. Plan edits made through MCP are always proposals (change sets) that you preview and then apply or discard. Nothing can be deleted through MCP. For how the safety model works, see the MCP overview.
Two transports expose the same tools.
| Transport | Endpoint | Auth | Writes enabled by |
|---|---|---|---|
| Streamable HTTP | POST http://localhost:8787/mcp |
Authorization: Bearer <api key>, never a browser cookie |
GLIDEWORTH_MCP_ALLOW_WRITES=true on the server and a key with write scope |
| stdio | node apps/api/dist/mcp/stdio.js |
None: a local process you start | GLIDEWORTH_MCP_ALLOW_WRITES=true in the process environment |
The HTTP endpoint is stateless, so it works behind plain proxies. Which tools a key sees depends on its scopes: read
gets the read and compute tools, simulate only compute tools, and write with the server flag adds the write tools.
Before you start: a running instance (for HTTP) or a built checkout (for stdio, pnpm build), and a key:
pnpm keys:create -- --name claude-readonly --scopes read # analysis only
pnpm keys:create -- --name claude-editor --scopes read,write # can propose and apply change sets
Use absolute paths in every stdio configuration. Do not launch a stdio server through pnpm run: pnpm prints a banner to
stdout, which is the protocol channel. Logs go to stderr.
Claude Code
Over HTTP, with the server running:
claude mcp add --transport http glideworth http://localhost:8787/mcp \
--header "Authorization: Bearer glideworth_xxxxxxxx_..."
Over stdio, with nothing else running (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
Without a build, run the source through tsx instead:
-- /abs/path/to/glideworth/apps/api/node_modules/.bin/tsx --conditions=@glideworth/source /abs/path/to/glideworth/apps/api/src/mcp/stdio.ts.
A project-scoped .mcp.json:
{
"mcpServers": {
"glideworth": {
"type": "http",
"url": "http://localhost:8787/mcp",
"headers": { "Authorization": "Bearer ${GLIDEWORTH_MCP_KEY}" }
}
}
}
Claude Desktop
Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\) and
restart the app.
stdio, reading the SQLite file directly:
{
"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 own copy:
{
"mcpServers": {
"glideworth": {
"command": "docker",
"args": ["exec", "-i", "-e", "GLIDEWORTH_MCP_ALLOW_WRITES=false", "glideworth", "node", "dist/mcp/stdio.js"]
}
}
}
HTTP, through the mcp-remote bridge for clients that only speak stdio:
{
"mcpServers": {
"glideworth": {
"command": "npx",
"args": ["-y", "mcp-remote", "http://localhost:8787/mcp", "--header", "Authorization:${GLIDEWORTH_AUTH}"],
"env": { "GLIDEWORTH_AUTH": "Bearer glideworth_xxxxxxxx_..." }
}
}
}
Newer Claude Desktop builds can add the same URL and header as a custom connector (Settings, Connectors) instead of the bridge.
Cursor and other clients
Use the generic settings of your client:
- HTTP: the URL
http://localhost:8787/mcpand the headerAuthorization: Bearer <key>. - stdio: run
node apps/api/dist/mcp/stdio.jswithGLIDEWORTH_DB_PATHset. - To try it without a client:
npx @modelcontextprotocol/inspector, and point it at either transport.
Where Cursor keeps its MCP settings is Cursor’s own documentation, not Glideworth’s.
Remote clients with OAuth
Hosted clients that connect by URL sign in with OAuth 2.1: the first request to /mcp returns 401 with a
WWW-Authenticate header, the client discovers the server, registers itself, sends you to a consent screen served by
Glideworth, and redeems the code with PKCE. You can grant fewer scopes than asked, never more, and your role caps them.
Put Glideworth behind TLS and set GLIDEWORTH_PUBLIC_URL. Revoke a connection under Settings, then Connected apps.
See Authentication.
Ask about your plan
Once connected, try:
- “Summarise my finances and plan.”
- “What is my chance of success, and why does it fail when it fails?”
- “What if I retire three years earlier? Save it as a branch.” (needs writes)
- “What is the most I can spend at 90% success?”
- “Review my assumptions and show what changing the top finding would do.” (needs writes)
See the worked examples for the tool calls behind each.
Troubleshooting
- No write tools: the flag is off or the key lacks
write. Reconnect after changing either. 401from/mcp: MCP needs an API key or an OAuth token; the browser sign-in is not accepted.- A stdio server fails to start in Claude Desktop: use absolute paths, make sure the build exists, and do not launch via
pnpm run. - A tool returns a
jobIdandrunning: it did not finish withinwaitseconds; callget_jobwithwait: 60. planId is required here: more than one household or main plan exists; calllist_householdsorlist_plans.CHANGESET_CONFLICT: the plan changed after the proposal. Re-read and propose again.PATCH_CONFLICT: an operation’s target does not exist; check ids withget_plan.
Last checked against the code on .