Skip to content

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.

Terminal window
codex plugin marketplace add bestdan/finplan-plugin
codex plugin add finplan@finplan-plugin

This installs:

  • MCP server connection — finplan, at https://mcp.finplan.tools/mcp. Check it with codex 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”.

FinPlan requires a free account. Run:

Terminal window
codex mcp login finplan

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

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.

Start Codex and ask a question that needs a calculation:

Terminal window
codex
Calculate federal income tax for $85,000 filing single in 2026

Codex should call a FinPlan tool rather than answer from memory. If it fails:

  1. Run codex mcp list. The finplan row should read enabled, and its Auth column should not read Not logged in. If it does, run codex mcp login finplan.
  2. The hosted server sleeps when idle, so the first call after a quiet spell can time out. Ask Codex to retry.
  3. See Troubleshooting for 401 errors and missing tools.

Refresh the marketplace, then install the plugin again to pick up the new version:

Terminal window
codex plugin marketplace upgrade finplan-plugin
codex plugin add finplan@finplan-plugin

If you would rather add only the MCP server, skip the plugin and run:

Terminal window
codex mcp add finplan --url https://mcp.finplan.tools/mcp
codex mcp login finplan

Without 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't
listed, 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"

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 = false

Then register a server that sends the key:

Terminal window
codex mcp add finplan --url https://mcp.finplan.tools/mcp --bearer-token-env-var FINPLAN_API_KEY

Its approval setting goes under [mcp_servers.finplan]. Don’t commit the key or a file containing it to source control.