Connect EzFin to your MCP client

Server details

You do not need to create or paste an EzFin API key. A compatible MCP client discovers the OAuth endpoints and opens the authorization flow in your browser.

Quick start

Codex CLI or IDE extension

Codex shares MCP configuration between the CLI and IDE extension.

codex mcp add ezfin --url https://api-ezfin.azifexlab.net/api/v1/mcp
codex mcp list

Or add the server directly to ~/.codex/config.toml:

[mcp_servers.ezfin]
url = "https://api-ezfin.azifexlab.net/api/v1/mcp"

The command and shared configuration behavior follow the official OpenAI MCP setup documentation.

Claude Code

Add the server for the current project:

claude mcp add --transport http ezfin https://api-ezfin.azifexlab.net/api/v1/mcp
claude mcp list

To make it available to every Claude Code project, add it with user scope:

claude mcp add --transport http --scope user ezfin https://api-ezfin.azifexlab.net/api/v1/mcp

Run /mcp inside Claude Code to inspect the connection and start OAuth.

VS Code with GitHub Copilot

Create .vscode/mcp.json in your project:

{
  "servers": {
    "ezfin": {
      "type": "http",
      "url": "https://api-ezfin.azifexlab.net/api/v1/mcp"
    }
  }
}

Open Copilot Chat, switch to Agent mode, enable ezfin in the tools picker, and follow the browser authorization prompt.

Cursor

Create or update ~/.cursor/mcp.json:

{
  "mcpServers": {
    "ezfin": {
      "url": "https://api-ezfin.azifexlab.net/api/v1/mcp"
    }
  }
}

Restart Cursor, enable the ezfin server, and complete authorization.

Any other MCP client

Name: ezfin
Transport: Streamable HTTP
URL: https://api-ezfin.azifexlab.net/api/v1/mcp
Authentication: OAuth (automatic discovery)

The client must support remote Streamable HTTP MCP servers and OAuth 2.1 authorization-server and protected-resource discovery. If it asks for a static bearer token instead of opening a browser, it is not using EzFin’s supported authentication flow.

Authorize your workspace

On the first authenticated connection:

1. Your MCP client opens the EzFin authorization page.
2. Enter the workspace serial you want the client to access.
3. Select Continue with Google and use the Google account attached to your EzFin membership.
4. Return to the client. It can now call EzFin tools within that workspace and the scopes it requested.

The issued session is audience-bound to the MCP server and selected workspace. Tool arguments cannot switch it to another workspace.

Start with the skill tool

Before asking the client to change financial data, have it call EzFin’s read-only skill tool. It returns the authoritative operating guide, including clarification, confirmation, idempotency, transfer, and image rules.

Use the EzFin skill tool first. Then show my account balances and explain which
workspace you are connected to. Do not make any changes.

Example tasks

Record an expense

Use EzFin to record Rp125,000 for lunch at McDonald's from BCA Main today.

EzFin passes the original wording through its canonical parser. If an account, amount, date, or category is unclear, the tool returns needs_clarification instead of guessing.

Record an internal transfer

Use EzFin to transfer Rp2,000,000 from BCA Main to GoPay.

Use record_transfer for money moving between your own accounts. EzFin does not classify an internal transfer as income or expense.

Read balances and metrics

Use EzFin to show my account balances, September cash flow, and savings rate.

Balances and metrics come from the API’s deterministic calculations, not from the client model’s arithmetic.

Reconcile an account

Use EzFin to reconcile BCA Main. The balance shown by the bank is Rp8,450,000.

Reconciliation can return a proposed adjustment that requires confirmation before EzFin writes it.

Available tools

Result states

Do not describe a mutation as successful unless the tool returns completed.

Current limitations

• Image input transport is not yet available through MCP. Provide the original transaction text instead of asking a client to infer image-only financial facts on EzFin’s behalf.
• The production authenticated end-to-end MCP client smoke test is pending.

Troubleshooting

The browser sign-in does not open

Confirm that your client supports remote HTTP MCP servers with OAuth. Remove and re-add the server, then inspect the client’s MCP connection screen or logs.

Workspace authorization fails

Use a Google account that already has an EzFin workspace membership and confirm the workspace serial is correct.

The server returns 401 invalid_token

Reconnect the server so the client can repeat OAuth discovery and refresh its session. Do not paste a normal EzFin API token into the MCP configuration; API and MCP tokens intentionally use different audiences.

A write asks for confirmation

This is expected for destructive or high-risk changes. Review the server’s summary and explicitly confirm or cancel it in the client.

Health and discovery checks

• API health
• OAuth authorization-server metadata
• MCP protected-resource metadata