FinAegis MCP Server
Connect Claude Desktop, Cursor, Continue.dev, or any spec-compliant agent to your FinAegis account through one OAuth-protected JSON-RPC endpoint.
Or use the remote URL directly: https://mcp.zelta.app/mcp
Connect in 30 seconds
First launch opens a browser for OAuth consent. Token persists per-client; subsequent launches are silent.
Claude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"finaegis": {
"url": "https://mcp.zelta.app/mcp"
}
}
}
Cursor
Settings → Features → MCP → Add Server.
URL: https://mcp.zelta.app/mcp
Continue.dev uses the same URL under experimental.modelContextProtocolServer.
Stdio-only clients
For older clients without remote streamable-HTTP support:
npx -y @finaegis/mcp
Persists token in OS keychain. --logout clears it.
Discovery
Live OAuth metadata clients use to bootstrap the handshake.
https://mcp.zelta.app/.well-known/oauth-protected-resource
RFC 9728 — protected resource metadata
https://zelta.app/.well-known/oauth-authorization-server
RFC 8414 — authorization server metadata
https://zelta.app/oauth/register
RFC 7591 — dynamic client registration
Scope catalog
Users grant scopes on the consent screen at first connection. Each tool requires exactly one scope; mpp.discovery is public.
| Scope | Description |
|---|---|
accounts:read |
Read account profile and balances |
accounts:write |
Create new accounts |
payments:read |
Read payment status |
payments:write |
Send payments (subject to spending limit) |
transactions:read |
Read transaction history and spending analysis |
exchange:read |
Get exchange rate quotes |
exchange:write |
Execute exchange trades (subject to spending limit) |
ramp:read |
Read on/offramp session status |
ramp:write |
Start on/offramp sessions (subject to spending limit) |
sms:send |
Send SMS messages (paid per-message via x402) |
Tool catalog (v1)
12 enabled tools. Disabled tools are omitted from tools/list AND return -32004 if invoked. Operators flip them via MCP_TOOL_* env vars.
| Tool | Scope | Type | Notes |
|---|---|---|---|
account.balance |
accounts:read
|
read | — |
account.create |
accounts:write
|
write | idempotency_key required |
payment.status |
payments:read
|
read | — |
payment.transfer |
payments:write
|
write | idempotency_key + spending limit |
transactions.query |
transactions:read
|
read | — |
spending.analysis |
transactions:read
|
read | — |
exchange.quote |
exchange:read
|
read | — |
exchange.trade |
exchange:write
|
write | idempotency_key required |
ramp.start |
ramp:write
|
write | idempotency_key required |
ramp.status |
ramp:read
|
read | — |
mpp.discovery |
public | read | — |
sms.send |
sms:send
|
write | idempotency_key required |
Live schemas: call tools/list on an authenticated session to fetch every tool's inputSchema and outputSchema — the wire is the source of truth.
Resources (read-context)
URI primitives an agent can pull into its window without a tool call — cheaper, cached, friendlier for browsing.
| URI pattern | Scope |
|---|---|
account://profile |
accounts:read |
account://balance/{currency} |
accounts:read |
transactions://recent |
transactions:read |
transaction://{id} |
transactions:read |
JSON-RPC error codes
Wire-protocol errors. Tool-level failures use isError: true in the result envelope, not these codes.
| Code | Name | Meaning |
|---|---|---|
-32001 | UNAUTHENTICATED | Missing or expired bearer; refresh and retry. Returned with 401 + WWW-Authenticate. |
-32002 | IDEMPOTENCY_KEY_REUSED | Same key used with different args. |
-32003 | SPENDING_LIMIT_EXCEEDED | Daily limit hit; wait for window reset. |
-32004 | TOOL_DISABLED | Operator-disabled via MCP_TOOL_*. |
-32005 | IDEMPOTENCY_KEY_IN_FLIGHT | Concurrent retry of an in-progress write; back off. |
-32006 | USER_CONTEXT_REQUIRED | client_credentials grant cannot call user-bound tool. |
Built-in policies
Spending limits
Per-token, not per-scope. Default $500.00 / 24h rolling window. Slider on the consent screen lets the user pick a different cap. Reservations are atomic: the saga reserves before the tool runs and rolls back on any error.
Idempotency
Every write tool requires idempotency_key (UUID, ≤128 chars). Server caches result for 24h. Atomic Redis SET-NX lock prevents two concurrent retries from both executing.