Codex Setup
OpenAI’s Codex CLI can install the FinPlan plugin directly. The plugin connects the FinPlan MCP server and adds the FinPlan skill, which teaches Codex which tool fits each task and how money values are encoded. Codex signs you in through the browser, so you don’t need an API key.
These steps were checked against Codex CLI 0.166. Update first if yours is older: codex update.
Install the Plugin
Section titled “Install the Plugin”codex plugin marketplace add bestdan/finplan-plugincodex plugin add finplan@finplan-pluginThis installs:
- MCP server connection —
finplan, athttps://mcp.finplan.tools/mcp. Check it withcodex mcp list. - Skill —
finplan:finplan. Codex loads it when you ask a financial-planning question, so it reaches for FinPlan’s tools instead of estimating.
The plugin’s /finplan:* slash commands are Claude Code features and do not appear in Codex. Ask for the same thing in plain words instead: “set up my FinPlan profile”, “run a checkup on my plan”.
Sign In
Section titled “Sign In”FinPlan requires a free account. Run:
codex mcp login finplanYour browser opens to sign in with Google, an email and password, or an email magic link. Codex stores the token, which lasts 30 days. When it expires, run the same command again.
On a machine with no browser, such as an SSH session, add --no-browser. Codex prints a URL: open it on any device, sign in, then paste the address your browser lands on back into the terminal.
Skip the Approval Prompts (Recommended)
Section titled “Skip the Approval Prompts (Recommended)”Every FinPlan tool is a calculation or a read or write of your own planning data on the FinPlan server. To let them run without approving each call, add this to ~/.codex/config.toml:
[plugins."finplan@finplan-plugin".mcp_servers.finplan]default_tools_approval_mode = "approve"Some FinPlan tools return a link to a large result file, such as a projection or a chart’s data, which Codex downloads with curl. Codex’s default sandbox has no network access, so it may ask before each download. Approve those; they only reach mcp.finplan.tools.
Verification
Section titled “Verification”Start Codex and ask a question that needs a calculation:
codexCalculate federal income tax for $85,000 filing single in 2026Codex should call a FinPlan tool rather than answer from memory. If it fails:
- Run
codex mcp list. Thefinplanrow should readenabled, and its Auth column should not readNot logged in. If it does, runcodex mcp login finplan. - The hosted server sleeps when idle, so the first call after a quiet spell can time out. Ask Codex to retry.
- See Troubleshooting for 401 errors and missing tools.
Updating
Section titled “Updating”Refresh the marketplace, then install the plugin again to pick up the new version:
codex plugin marketplace upgrade finplan-plugincodex plugin add finplan@finplan-pluginWithout the Plugin
Section titled “Without the Plugin”If you would rather add only the MCP server, skip the plugin and run:
codex mcp add finplan --url https://mcp.finplan.tools/mcpcodex mcp login finplanWithout the skill, Codex is more likely to estimate a tax or projection from memory. Add this to ~/.codex/AGENTS.md so it uses the tools:
For personal-finance questions that depend on a calculation (taxes,retirement, Social Security, RMDs, mortgages, savings goals, projections),use the FinPlanTools MCP tools instead of estimating. If a tool you need isn'tlisted, find it with search_tools. Money values are in cents.The approval setting for a server added this way goes in its own table:
[mcp_servers.finplan]default_tools_approval_mode = "approve"If Browser Sign-In Is Impossible
Section titled “If Browser Sign-In Is Impossible”Create an API key as described in Authentication and put it in an environment variable, FINPLAN_API_KEY. If you installed the plugin, turn off its server but keep its skill: in ~/.codex/config.toml, add enabled = false to the plugin’s server table. If you added the approval setting above, that table already exists; add the line to it rather than writing the table header a second time, which Codex rejects. Otherwise, add the whole table:
[plugins."finplan@finplan-plugin".mcp_servers.finplan]enabled = falseThen register a server that sends the key:
codex mcp add finplan --url https://mcp.finplan.tools/mcp --bearer-token-env-var FINPLAN_API_KEYIts approval setting goes under [mcp_servers.finplan]. Don’t commit the key or a file containing it to source control.