Connect Codex to Finaxis
Codex, the OpenAI agent that works in your terminal, connects to Finaxis through its MCP server. Once connected, it reads your customers, invoices, payments and aging, and answers your questions or prepares your work, never beyond the rights of the access you give it.
Before you start
- The Codex CLI installed and signed in to your OpenAI account.
- To choose between your own access and a service account, read Choose how an AI agent connects to Finaxis.
Connect with your own access
- In a terminal, add the Finaxis MCP server to Codex. Codex saves it in ~/.codex/config.toml, detects that Finaxis asks for a sign-in and opens your browser on Finaxis.
codex mcp add finaxis --url https://api.finaxis.ai/mcp
- If the browser did not open, or to connect again later, start the connection yourself.
codex mcp login finaxis
On a machine without a browser, add --no-browser: Codex prints the address to open, then asks for the address your browser lands on, even if that page cannot load.
- If Finaxis asks you to log in, log in as usual. A page named Connect Codex to Finaxis opens.
- Under Portal, choose the instance the agent will work in. A connection works on one instance only.
- Under What it may do, uncheck the scopes the agent should not have, for example every write scope to start. The agent never goes beyond your rights, whatever you check.
- Click Connect, then go back to your terminal.
Ask Codex a question about your receivables, for example: Which customers are the most overdue in Finaxis, and for how much? With the read scopes alone, Codex sees the eight read tools of Finaxis. The same connection works with codex exec for a scripted run.
Please note: In Finaxis, the connection appears as Codex under Connected apps. See Choose how an AI agent connects to Finaxis to follow or revoke it.
Connect with a service account
For a job that runs without you, use a service account. Its token lasts one hour: a small script gives Codex a fresh one, and Codex runs it again when Finaxis refuses an expired token.
- Create a service account with the scopes the job needs, then copy its client ID and secret.
- Save them in a file only you can read.
# ~/.config/finaxis/service-account.env (readable by you only: chmod 600)
FINAXIS_CLIENT_ID=fxc_...
FINAXIS_CLIENT_SECRET=fxs_...
- Create the script that prints a fresh token as a header, then make it executable with chmod 700.
#!/usr/bin/env bash
# Prints an Authorization header with a fresh token for a Finaxis service account.
# The token lasts one hour: the agent runs this script each time it connects.
set -euo pipefail
. "$HOME/.config/finaxis/service-account.env"
token=$(curl -sf -u "$FINAXIS_CLIENT_ID:$FINAXIS_CLIENT_SECRET" \
-d grant_type=client_credentials https://api.finaxis.ai/v1/oauth/token \
| python3 -c 'import sys, json; print(json.load(sys.stdin)["access_token"])')
printf '{"Authorization": "Bearer %s"}\n' "$token"
- Declare a second server in ~/.codex/config.toml, under a different name, with the script as its http_headers_helper.
# ~/.codex/config.toml
[mcp_servers.finaxis_sa]
url = "https://api.finaxis.ai/mcp"
http_headers_helper = "/home/you/.config/finaxis/finaxis-headers.sh"
Please note: Keep a separate name for the service account server. When Codex holds a connection approved by a person for a server, that connection takes precedence over the header of the script.
Troubleshooting
| Situation | What to do |
|---|---|
| Codex says the server needs a login | Run codex mcp login finaxis and approve the connection in Finaxis. |
| The browser cannot open the page after you click Connect | That is expected with --no-browser: copy the address from the address bar and paste it in the terminal. |
| The service account server uses your own access | It shares its name with the server you logged in to. Give it its own name, such as finaxis_sa. |
| A tool you expected is missing | The scopes you approved hide it. Edit the connection in Finaxis, or connect again and check the scope. |
| The script returns an error | The secret expired or was replaced: rotate it and update the file. |
Need help connecting your agent? Write to support@finaxis.ai with the request id from the request log, and our team will help you.
Related articles
Can't find what you're looking for?
Our support team is here to help.