MCP Tool Access#
Overview#
Sure exposes a Model Context Protocol (MCP) server at POST /mcp, allowing external AI assistants (Claude Desktop, GPT agents, custom clients) to call financial tools against a user's Sure data . The protocol is JSON-RPC 2.0; the server announces protocol version 2025-03-26 .
The MCP tools are the same functions used by Sure's built-in AI assistant .
Enabling the Endpoint#
For legacy bearer-token authentication, set these two environment variables:
| Variable | Purpose |
|---|---|
MCP_API_TOKEN | Bearer token clients must send |
MCP_USER_EMAIL | Email of the Sure user whose data is exposed |
Both variables are required for the legacy token flow. OAuth clients using the MCP discovery and dynamic registration endpoints do not need these variables.
The endpoint returns HTTP 503 until both are set . The assistant gains read access to all financial data for the specified user's family .
Authentication#
MCP supports OAuth authorization-code flow for clients such as Claude Code. Clients should discover the protected-resource metadata, register dynamically, request the advertised read_write scope, and send the resulting access token as a Bearer token. Dynamically registered clients are assigned this scope so their tokens can authenticate to MCP.
For self-hosted deployments or clients without OAuth support, requests may use the legacy MCP_API_TOKEN as a Bearer token:
Authorization: Bearer <MCP_API_TOKEN>
The controller supports two token modes :
- Doorkeeper OAuth tokens with
read_writescope - Environment-based tokens via
MCP_API_TOKEN+MCP_USER_EMAIL
Protocol Methods#
The MCP controller dispatches three JSON-RPC methods:
| Method | Description |
|---|---|
initialize | Handshake — returns server info and capabilities |
tools/list | Lists all tools with JSON schemas |
tools/call | Executes a tool |
Available Tools#
All tools inherit from Assistant::Function, which provides schema validation and family-scoped data helpers. They are registered in Assistant.function_classes, which now accepts a user parameter to conditionally include preview tools based on user permissions and preview feature access.
| Tool | Source | Description |
|---|---|---|
get_transactions | get_transactions.rb | Paginated transaction history; filter by date, account, category, merchant, tag, search query |
get_accounts | get_accounts.rb | Account names, balances, classifications, 5-year monthly history |
get_holdings | get_holdings.rb | Investment/crypto holdings; filter by account and ticker |
get_balance_sheet | get_balance_sheet.rb | Net worth, assets, liabilities, debt-to-asset ratio, monthly history |
get_income_statement | get_income_statement.rb | Income/expense totals by category for a date range with savings rate |
import_bank_statement | import_bank_statement.rb | Extracts transactions from PDFs via a configured LLM (Anthropic/OpenAI); creates imports for review |
search_family_files | search_family_files.rb | Search documents uploaded through the import flow. Note this is the vector-store document index, not the Statement Vault — statements archived via upload_account_statement are not searchable through it |
Preview Tools#
These additional tools appear only when the MCP user has opted into preview features (Settings → Preferences). Until then they are absent from tools/list, and calling one by name returns an "Unknown tool" error. The Statement Vault tools additionally require the user to be an admin or member, matching the permissions enforced in the web UI.
| Tool | Description |
|---|---|
upload_account_statement | Store a statement document (PDF/CSV/XLSX) in the Statement Vault; deduplicates by SHA-256 |
list_account_statements | List vault documents with their SHA-256, period, linked account and review status |
get_account_statement | One statement's details and its reconciliation checks against the ledger — present only once someone has entered the statement's opening/closing balances in the web UI, since nothing extracts them from the document. Does not return the file: stored documents are served only to a signed-in browser session |
get_statement_coverage | Month-by-month statement coverage for an account: covered, missing, mismatched, ambiguous, duplicate, not_expected, each with a reconciliation status |
record_valuation | Record an account's value on a date, with a required source citation |
They exist for agents that maintain a document-backed record of a family's wealth over time. See Wealth history with an external agent harness.
Security#
Transient Session Isolation#
Each request creates a short-lived session scoped to the MCP_USER_EMAIL user, then discards it . This prevents impersonation-state leaks from other parts of the app.
Pipelock Security Proxy#
For production, route external agents through Pipelock (port 8889) rather than directly to Sure's /mcp (port 3000) . Pipelock adds:
- DLP scanning (secret exfiltration detection)
- Prompt injection detection
- Tool poisoning detection
- Signed receipts / audit trail
Pipelock is configured in compose.example.ai.yml .
Key Source Files#
| File | Role |
|---|---|
app/controllers/mcp_controller.rb | JSON-RPC dispatch, auth, session isolation |
app/controllers/settings/mcp_controller.rb | Settings UI + token revocation |
app/models/assistant/function.rb | Base class for all tools |
app/models/assistant.rb | Tool registry (function_classes) |
docs/hosting/mcp.md | Full setup and usage documentation |
See Also#
- External AI Assistant Configuration — connecting Sure's chat to an external agent
- Pipelock Security Proxy docs — MCP traffic scanning setup
- MCP Specification