Skip to content

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.

Paste this into your agent’s chat:

Read https://finplan.tools/install.md and set up FinPlanTools for me

That 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.

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

  1. Make sure you’re using the correct URL: https://mcp.finplan.tools/mcp
  2. Check your network connection and firewall settings
  3. Restart your AI assistant and try again
  1. 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.
  2. 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.
  3. OAuth-issued tokens expire after 30 days. If Claude worked before but fails now, sign in again: in Claude Code, run /mcp and re-authenticate FinPlan; in Codex, run codex mcp login finplan; in Claude Desktop or Claude Web, disconnect and reconnect the connector in Settings.
  1. Ask the agent to check if it has access to FinPlan tools.
  2. Double-check that you’ve enabled the FinPlan connector in your settings
  3. Try asking a simple question first: “What filing statuses are available?”
  4. Make sure you’re giving enough information — for example, tax calculations need an income amount, filing status, and tax year

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.”

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.