How to Connect Codex to dfin.pro MCP

1.0 Before You Start

You will need:

• A dfin.pro account. Verify your email address if dfin.pro asks you to.
• Codex, either the desktop app or the CLI.
• Approval from your organization, if it manages plugins or MCP connections. Ask your workspace admin if the options below are missing.

Codex's menus change from time to time, so a label may look slightly different in your version. If you already have a working dfin.pro connection in Codex, you can keep using it and skip ahead to Try a research question.

2.0 Connect using the plugin and OAuth

The dfin.pro plugin includes the MCP connection and the research skills. You only need to install it once, using either the desktop app (section 2.1) or the CLI (section 2.2). You do not need to add a separate MCP server or install the skills yourself.

2.1 Desktop App: Add the plugin marketplace

A marketplace is a source Codex installs plugins from. In the Codex desktop app, open Settings → Plugins, click Add, then choose Add a marketplace.

Enter dfin-pro/dfin-financial-mcp in Source and click Add marketplace. Leave the other fields as they are, unless your organization gave you different settings.

Install the plugin

Open the Personal tab in the plugin directory, find dfin-financial-mcp under dfin.pro, and click its + button to install it.

Open the installed plugin. Its details page should list the dfin MCP server and five research skills. Seeing them there doesn't mean you're signed in yet; that's the next step.

Authorize the MCP connection

Codex normally signs in to the MCP connection automatically when you install the plugin, so there is usually nothing more to do. You only need to act if Codex asks you to approve something, shows an error message, or the connection fails.

To check, open MCP servers and find dfin under From plugins. If it asks you to connect or authenticate, use that control and approve access on the dfin.pro page that opens in your browser. If you are already signed in to dfin.pro in that browser, this goes faster.

If there is no way to authenticate in the app, open a terminal on the same computer and run codex mcp login followed by the server name that Codex shows. Then open a new Codex chat and try a research question.

2.2 CLI: Installation for CLI users

If you use the Codex CLI, work on the computer that runs Codex.

1. Add the same marketplace:

codex plugin marketplace add dfin-pro/dfin-financial-mcp

1. Start Codex, enter /plugins, choose the dfin.pro marketplace, and install dfin-financial-mcp.
2. Start a new CLI session so Codex loads the plugin's skills and tools.
3. Enter /mcp to find the connector that came with the plugin. If it needs authorization, run codex mcp login followed by the name shown, and approve access in your browser.

Once you are connected, try a research question.

3.0 Connect just the MCP

If you already installed the plugin in section 2.0, skip ahead to Try a research question.

A direct MCP connection gives Codex the dfin.pro tools without the plugin's skills. Pick one of the methods below: ask Codex to set it up (section 3.1), use the app (section 3.2), or edit the config file (section 3.4). Use OAuth unless your Codex version or organization doesn't support it; an API key is the fallback. If the plugin connection already works, don't add a direct server as well.

3.1 Ask Codex to set up the MCP

Paste this prompt into Codex on the computer where you want the connection. Codex checks what is already set up, adds a direct MCP server only if one is missing, and leaves the browser sign-in to you:

Use https://www.dfin.pro/agents/codex.md#compatibility to connect this Codex host directly to the dfin.pro MCP server with OAuth. Preserve any working connection. Do not install the plugin or separate skills. Ask me to complete browser sign-in and consent, then verify a live dfin.pro query.

When Codex finishes, try a research question. If Codex can't reach the settings on that computer, follow the app steps in section 3.2 or the config file steps in section 3.4 below yourself.

3.2 Configure the MCP in the app

In the Codex desktop app, open Settings → MCP servers. If dfin isn't listed yet, click Add Server.

Choose Streamable HTTP and fill in the form:

• Name: dfin
• URL: https://www.dfin.pro/mcp
• Bearer token env var: leave this empty for OAuth. If you are using an API key instead, first set the key in section 3.3, then enter DFIN_API_KEY here.

Click Save. The screenshot shows the API-key version of the form:

Make sure the server is switched on. If you are using OAuth, click its sign-in (authentication) button and approve access in your browser. If your version of the app has no Bearer token env var field, set up an API-key connection in the config file instead (section 3.4).

Once the server is on and you have signed in, try a research question.

3.3 Set the API key, if needed

Only follow this section if you can't use OAuth. An API key is a private code that identifies your account, so keep it to yourself and out of chats and config.toml. Create one on your dfin.pro Account page.

Codex reads the key from an environment variable called DFIN_API_KEY. Set that variable in the environment that launches Codex:

Set DFIN_API_KEY yourself in the environment that launches the intended client. Never paste the key into a conversation. If it is already configured, reuse it without appending another setting.

For macOS Zsh:

echo 'export DFIN_API_KEY="paste-your-api-key-here"' >> ~/.zshrc
source ~/.zshrc

For Linux Bash:

echo 'export DFIN_API_KEY="paste-your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

For Windows PowerShell:

[Environment]::SetEnvironmentVariable("DFIN_API_KEY", "paste-your-api-key-here", "User")

For Windows Command Prompt:

setx DFIN_API_KEY "paste-your-api-key-here"

Reopen the terminal after setting a Windows user environment variable. Desktop apps may require the variable in their launch environment too; follow the client's guidance. Keep credentials private and out of version control.

After you set the variable, restart Codex so it picks up the new value. Then go back to the app steps in section 3.2 or the config file steps in section 3.4.

3.4 Edit config.toml

Codex keeps its MCP settings in ~/.codex/config.toml, or in a trusted project's .codex/config.toml. On Windows, your personal file is usually C:\Users\<your-user>\.codex\config.toml. Leave your other settings as they are, and make sure there is only one dfin entry.

To connect with OAuth, add this entry:

[mcp_servers.dfin]
enabled = true
url = "https://www.dfin.pro/mcp"

If you can't use OAuth, set the API key in section 3.3 and add this entry instead:

[mcp_servers.dfin]
enabled = true
url = "https://www.dfin.pro/mcp"
bearer_token_env_var = "DFIN_API_KEY"

Save the file and open a new Codex chat. For OAuth, run codex mcp login dfin in a terminal on the same computer and approve access in your browser. Then try a research question.

4.0 Install the skills

If you installed the plugin, the skills came with it, so you can skip ahead to Try a research question.

If you connected directly to the MCP server, you can add the dfin.pro skills yourself. The plugin repository lists every skill and what it does. The steps below install one skill at a time, using dfin-research as the example. Repeat them for any other skills you want.

If your Codex desktop app has a / menu, open Skill Installer from it:

Enter the repository URL and give skills/dfin-research as the folder. The installer in your version of Codex may look a little different from this older screenshot:

Or you can ask Codex to install a missing skill for you with $skill-installer:

$skill-installer Install the dfin-research skill from the skills/dfin-research folder in https://github.com/dfin-pro/dfin-financial-mcp for this Codex installation, only if it is missing. Preserve my existing MCP connection.

Check that dfin-research now appears in your skill list. To add another skill, repeat the installation with its folder name from the repository. If the new skill doesn't show up, or Codex asks you to restart, see How to restart Codex.

5.0 Try a research question

First, check the connection. In the desktop app, open Settings → MCP servers. In the CLI, enter /mcp. Confirm that dfin is listed as connected.

Then open a new Codex chat (or a new CLI session) and try a question that needs financial data:

/dfin-research Which are the key reporting metrics used by Shift4 Payments?

Codex should show that it is using dfin.pro tools, then answer with figures, dates, and links to its sources. If it answers without using dfin.pro, or the tools are missing, see Troubleshooting.

6.0 Using skills

Skills are ready-made workflows that show Codex how to approach a task: what evidence to look for and how to present the result. The plugin installs the dfin.pro skills for you. If you connected directly, you can add them in section 4.0.

To use the research skill, start your message with /dfin-research, as in the example above. In versions of Codex that support it, you can also type $ to pick a skill from a list. Use the name your version shows, which may include the plugin name.

The plugin includes five skills in total: research, stock screens, semantic screens, saving notes, and monitoring recent filings. The plugin repository describes each one.

Each skill is a folder with a SKILL.md text file in it, so you can edit a skill or write your own. A good approach is to ask Codex to make the first edits, then fine-tune them by hand. Save your version under a different name so plugin updates don't overwrite your changes.

7.0 Troubleshooting

I can't find the plugin, or the dfin server is missing

• Check that the plugin and its dfin MCP server are both switched on. In the desktop app, look under Settings → Plugins and Settings → MCP servers. In the CLI, use /plugins and /mcp.
• Open a new chat, since Codex loads plugins and servers when a chat starts.
• If the options aren't there at all, update Codex to the latest version. If your organization manages Codex, ask your workspace admin whether plugins and MCP connections are allowed.
• If you connected directly instead of using the plugin, look for dfin under MCP servers (or in /mcp).

Codex doesn't show the new tools or skills

Starting a new chat is usually enough. If that doesn't help, fully quit Codex and open it again:

• Windows desktop app: right-click Codex in the taskbar or system tray and choose Exit.
• macOS desktop app: choose Codex → Quit Codex, press Cmd+Q, or use the quit option in the Dock menu.
• CLI: exit Codex and start it again. If you added DFIN_API_KEY after opening the terminal, close and reopen the terminal first.

Sign-in was cancelled or expired

Click the sign-in (authentication) button next to dfin under MCP servers, or run codex mcp login followed by the server name in a terminal. Approve access in the browser on the same computer that runs Codex.

Two dfin connections conflict

You may have both the plugin's connection and a direct one. Decide which you want to keep before removing either, and leave the one that works in place until the other is set up. Remove the extra entry from Settings → MCP servers, or delete the extra dfin entry from config.toml.

API-key errors

Check that DFIN_API_KEY is set in the environment that launches Codex, then restart Codex. If you launch Codex from a terminal, set the variable in that same terminal session or shell profile.

Codex is connected but the answer has no data

Being connected doesn't guarantee that every question returns data. Read the message Codex shows: if it mentions your credits, a rate limit, or missing data for a company, follow the next step it suggests. Signing in again won't fix those.

Still stuck?

Email [email protected] with your Codex version and the step where things went wrong. Please leave out API keys and private authorization links.