Aurify MCP Gateway

An MCP server that lets an AI agent (Hermes, Claude, any MCP client) do anything a user can do in the Aurify web app.

What it is, and what it deliberately is not

It is an adapter, not a microservice. It owns no database, no aggregate, no events, and no migrations. Every tool is a translation of an MCP call into a request against refina-web-bff — the same REST surface the web frontend uses — so there is exactly one implementation of every business rule, and it lives in the domain services.

Hermes ──MCP (Streamable HTTP)──► aurify-mcp ──REST──► refina-web-bff ──gRPC──► wallet / transaction / …
                Bearer aur_pat_…       │                    Bearer <5-min JWT>
                                       └──► refina-auth  (PAT → JWT exchange)

It is intentionally not folded into the BFF: the BFF is the hot path for the browser, tuned with a Redis read cache and a rate limiter for that traffic, whereas this needs long-lived protocol sessions, tool schema discovery, scope enforcement, and an audit trail. Different lifecycle, different blast radius.

Authentication

The agent presents an Aurify personal access token; the gateway exchanges it for a five-minute JWT and calls the BFF with that.

The exchanged JWT carries exactly the claims the BFF already expects, so no downstream service needed any change to support agents. The PAT is the durable credential and can be revoked at any time; the access token it yields is too short-lived to be worth stealing.

Scopes are enforced here, before any network call. The BFF still only checks the signature, exactly as it does for the browser.

Getting a token

# 1. Log in to Aurify and grab your JWT, then mint a PAT with only the scopes
#    the agent actually needs.
curl -X POST http://localhost:8080/auth/pat \
  -H "Authorization: Bearer <your login JWT>" \
  -H "Content-Type: application/json" \
  -d '{"name":"hermes","scopes":["wallet:read","transaction:read","transaction:write"]}'

# 2. Copy the `token` from the response — it is shown once and never again.

# 3. Revoke it whenever you like:
curl -X DELETE http://localhost:8080/auth/pat/<id> -H "Authorization: Bearer <JWT>"

Available scopes: wallet:read, wallet:write, transaction:read, transaction:write, budget:read, budget:write, investment:read, investment:write, analytics:read, profile:read, profile:write.

Tools

28 tools by default. Reads are unrestricted; writes are annotated readOnlyHint: false so the client prompts for confirmation.

Group	Read	Write
Wallets	list_wallets, get_wallet, get_wallet_summary, list_wallet_types	create_wallet, update_wallet
Transactions	list_transactions, get_transaction, list_categories	create_transaction, create_fund_transfer, update_transaction
Budgets	list_budgets	create_budget, update_budget, reset_budget
Analytics	get_financial_summary, get_balance_history, get_net_worth, get_transaction_analytics, get_category_transactions	—
Investments	list_investments, get_investment_summary, list_asset_codes	create_investment
Profile	get_profile	update_profile
System	—	refresh_cache

delete_wallet, delete_transaction, delete_budget and sell_investment are not registered at all unless MCP_ALLOW_DELETE=true. Filtering rather than rejecting means an agent never even sees them advertised.

Two conveniences are built in, because the web UI solves them in the frontend:

• create_fund_transfer fills in the reserved Cash In / Cash Out category ids itself, so they are absent from the tool schema.
• Tool descriptions explain the credit-line balance convention, so an agent does not mistake available credit for money owned.

Credit cards

A wallet whose wallet_type_nature is liability is a credit line. Its balance is the credit still available: spending lowers it, and paying the bill — a fund transfer into the wallet — restores it. Available credit is never part of net worth. The tool descriptions state this so the model does not have to infer it.

Running

npm install
cp .env.example .env      # point BFF_BASE_URL / AUTH_BASE_URL at your services
npm run build
npm start                 # POST /mcp, GET /health

npm test                  # unit tests
npm run lint              # typecheck

Configuration

Variable	Default	Purpose
PORT	8080	Listen port
BFF_BASE_URL	(required)	refina-web-bff base URL
AUTH_BASE_URL	(required)	refina-auth base URL, for PAT exchange
MCP_ALLOW_DELETE	false	Register destructive tools
REQUEST_TIMEOUT_MS	15000	Upstream request timeout

No JWT signing secret is needed: the gateway never mints tokens, it only asks the auth service for them.

Wiring up Hermes

Add to ~/.hermes/config.yaml and run /reload-mcp:

mcp_servers:
  aurify:
    url: http://127.0.0.1:8090/mcp
    headers:
      Authorization: Bearer aur_pat_xxxxxxxx
    enabled: true
    tools:
      include: [list_*, get_*, create_transaction, create_fund_transfer,
                update_transaction, create_budget, update_budget, refresh_cache]
      resources: false
      prompts: false

Verify with hermes mcp test aurify.

Use tools.include (an allowlist) rather than exclude — this is financial data, and an allowlist fails closed when new tools are added.

Operational notes

• Stateless. Each request builds its own server and transport, both torn down when the response ends. One caller's token can never leak into another's session, and the process can be restarted or scaled freely.
• Session cache. Exchanged JWTs are cached per token until 30s before expiry, and concurrent misses collapse into one exchange. In practice the first tool call in a turn costs a round trip to auth and the rest do not.
• Audit log. One JSON line per tool call on stdout, recording the tool, scope, outcome and duration. Argument keys are logged, never values — enough to audit without copying the user's financial data into the logs.
• Bind to localhost. Hermes runs as a host process, so publishing 127.0.0.1:8090 is sufficient. This gateway should not be exposed publicly.
• Shared rate limiter. The BFF's Redis rate limiter is shared with browser traffic, and its read cache can serve stale figures right after a write — hence the refresh_cache tool.