Connect Your Agent
Connect your AI assistant to FinPlan’s financial planning tools. Once connected, your assistant can calculate taxes, project investment growth, plan for goals, and more — using real math instead of guessing.
Fastest setup: let your agent do it
Section titled “Fastest setup: let your agent do it”Paste this into your agent’s chat:
Read https://finplan.tools/install.md and set up FinPlanTools for meThat page is written for agents: it tells yours how to connect from whichever app it runs in. Agents that can change their own config (Claude Code, Cursor, and friends) will do it themselves; the rest will walk you through the steps. The first FinPlan tool call opens your browser to sign in. If your agent can’t do it, use the per-agent guides below.
Authentication
Section titled “Authentication”FinPlan requires a free account. How you sign in depends on your agent:
- Claude Code, Claude Desktop, Claude Web — the first FinPlan tool call opens your browser to sign in (Google, email and password, or email magic link). The token is captured automatically and lasts 30 days.
- Codex — run
codex mcp login finplan, which opens the same browser sign-in. The token lasts 30 days. - ChatGPT, Gemini CLI, custom frameworks — browser OAuth from the agent isn’t supported yet. Create an account at mcp.finplan.tools/auth/signup — signing up shows your first API key (later keys: sign in at /auth/login and click Generate New Token) — and paste it into the
Authorization: Bearer fp_live_...header. Manual keys last 90 days.
Pick your agent below to get started:
| Agent | Setup Guide |
|---|---|
| Claude Code (Recommended) | Setup Guide |
| Claude Desktop | Setup Guide |
| Claude Web (claude.ai) | Setup Guide |
| ChatGPT | Setup Guide |
| Codex (CLI) | Setup Guide |
| Gemini CLI | Setup Guide |
| Other Tools & Frameworks | Setup Guide |
Troubleshooting
Section titled “Troubleshooting”Can’t Connect
Section titled “Can’t Connect”- Make sure you’re using the correct URL:
https://mcp.finplan.tools/mcp - Check your network connection and firewall settings
- Restart your AI assistant and try again
Unauthorized / 401 Errors
Section titled “Unauthorized / 401 Errors”- On Claude Code/Desktop/Web, the first tool call should open a browser for sign-in. If it didn’t, restart your agent and try again.
- If you’re using a manual API key (ChatGPT, Gemini CLI, custom frameworks), confirm it starts with
fp_live_, then sign in at /auth/login and check that its prefix is still in your key list and not marked expired (a revoked key drops off the list). Manual keys expire after 90 days. - OAuth-issued tokens expire after 30 days. If Claude worked before but fails now, sign in again: in Claude Code, run
/mcpand re-authenticate FinPlan; in Codex, runcodex mcp login finplan; in Claude Desktop or Claude Web, disconnect and reconnect the connector in Settings.
Tool Not Working
Section titled “Tool Not Working”- Ask the agent to check if it has access to FinPlan tools.
- Double-check that you’ve enabled the FinPlan connector in your settings
- Try asking a simple question first: “What filing statuses are available?”
- Make sure you’re giving enough information — for example, tax calculations need an income amount, filing status, and tax year
Only a Few Tools Show Up
Section titled “Only a Few Tools Show Up”If your agent lists just a handful of FinPlan tools — search_finplan_tools, describe_finplan_tool, manage_state, ping, search_tools, call_tool — that is expected on the hosted service at mcp.finplan.tools, not a broken connection. (Self-hosted servers advertise every tool unless they opt in to the reduced list.)
Sending all 80+ tool descriptions on every message costs roughly 45,000 tokens of your agent’s context before you’ve asked anything. So the server advertises a short list and lets your agent look the rest up on demand. Every tool is still available: your agent finds one with search_tools (or search_finplan_tools) and runs it either by name or through call_tool. Capable agents do this on their own — just ask for what you want.
If your agent insists a tool doesn’t exist, tell it to search first: “Use search_tools to find the mortgage calculator, then call it.”
Unexpected Results
Section titled “Unexpected Results”All monetary values are in cents internally. If you see a number like 8500000, that’s $85,000.00. Your AI assistant should translate this for you, but if something looks off, that’s likely why.