Connect Hermes Agent to Finaxis
Hermes Agent, the open-source agent from Nous Research, connects to Finaxis through its MCP server. It reads your customers, invoices, payments and aging, prepares customer files and plans, and can split the work between sub-agents, never beyond the rights of the access you give it.
Before you start
- Hermes Agent installed, with a model connected. These steps were tested with Hermes Agent 0.23.
- 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 Hermes with OAuth. Give it five minutes to connect, since Hermes waits while you approve the connection and stops after 30 seconds by default.
hermes mcp add finaxis --url https://api.finaxis.ai/mcp --auth oauth --connect-timeout 300
- Open the address Hermes prints. If Hermes runs on another machine than your browser, follow its instructions to paste the address your browser lands on.
- If Finaxis asks you to log in, log in as usual. A page named Connect Hermes Agent 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.
- Hermes lists the Finaxis tools it found (eight with the read scopes alone) and asks whether to enable them. Answer Y.
- Test the connection.
hermes mcp test finaxis
Then ask Hermes a question, in a chat or in one command:
hermes chat -q "Which customers are the most overdue in Finaxis, and for how much?"
Please note: Hermes can hand parts of a task to sub-agents working in parallel, for example one customer file per sub-agent. Each sub-agent uses the same Finaxis connection, within the same scopes.
Use a service account for scheduled jobs
For a job that runs alone, such as a weekly payer scorecard, use a service account. Its token lasts one hour, and Hermes reads it when it starts: a secrets command gives it a fresh one at each start.
- Create a service account with the scopes the job needs, then save its client ID and secret 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 the token in the form Hermes expects, then make it executable with chmod 700.
#!/bin/sh
# Prints FINAXIS_TOKEN=<fresh token> for Hermes. Hermes runs it each time it starts.
. "$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"])')
echo "FINAXIS_TOKEN=$token"
- Declare the server and the secrets command in ~/.hermes/config.yaml.
# ~/.hermes/config.yaml
mcp_servers:
finaxis_sa:
url: https://api.finaxis.ai/mcp
headers:
Authorization: "Bearer ${FINAXIS_TOKEN}"
secrets:
command:
enabled: true
command: "/home/you/.hermes/finaxis-token.sh"
helper_timeout_seconds: 10
override_existing: true
- Run hermes mcp test finaxis_sa: it should find the tools of the scopes you chose.
Please note: If FINAXIS_TOKEN is missing, Hermes skips the server and goes on with the others, without failing. Hermes reads the variable only from its own .env file or its secrets source, not from your shell. Check the server with hermes mcp test before you schedule a job.
A Hermes session that lasts more than an hour keeps its first token: start a new session for each scheduled run.
Troubleshooting
| Situation | What to do |
|---|---|
| Hermes says the connection timed out | Add --connect-timeout 300: the default 30 seconds is too short to approve the connection. |
| Hermes answers with your own access instead of the service account | The service account server did not start, often because FINAXIS_TOKEN is missing. Run hermes mcp test 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 token 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.