Mortgage tools your agent can use

FINLY helps people understand Israeli mortgages and identify questions worth checking with an advisor. We return sources, dates, assumptions and limitations. If the analysis finds no financial benefit, we say so honestly.

Documentation updated 10 September 2026. The live capability schemas are the authority for available tools and current limits.

Choose the service

These public services do not require a FINLY account. Private Office tools use separate OAuth authorization. The Customer monitoring extension described below awaits deployment and activation. Anonymous report requests never grant private account access.

Analyze a balance report

1. Call get_report_analysis_requirements with an empty object. Read the processing notice, supported files, limits and challenge.
2. Use the local file bytes and the released schema. Never supply a remote file URL or extra borrower identifiers.
3. Only present a successful result as an analysis. Deliver result.document.text or result.document.html to the person, keeping limitations beside the findings. A raw JSON response is for software, not the customer's report.
4. Follow the operation and recovery instructions returned by the service. A timeout alone does not establish that analysis failed; do not automatically upload the document again.

External OCR sends the mortgage report, including personal and financial data, to Google Document AI outside Israel. Select it only when the existing task authority covers that transfer: send external_ocr with authorization_basis: "existing_task", task_authorizes_external_processing: true, and the policy_version and text_sha256 from external_ocr_delegated_policy. FINLY requires no additional human approval roundtrip. This is the agent's attestation; the hash binds the supplier notice and does not prove the person saw or approved it. The agent is responsible for the scope of authority. Local-only processing is the default. Legacy separate approval through external_ocr_policy remains supported.

The standalone Node.js client writes a readable local report:

node agent-report-client.mjs --file "balance-report.pdf" --output "finly-analysis.html"

Add --task-authorizes-external-ocr only when the existing task authority includes that transfer. The client uses the validated current supplier notice automatically; no human hash copying is required. The legacy --approve-external-ocr CURRENT_HASH option is still available for a separate approval. The two flags are mutually exclusive; omitting both keeps processing local.

Use a .txt output name for UTF-8 text. Do not put report contents, result tokens or OAuth credentials into URLs, analytics or shared logs.

Find knowledge without guessing an identifier

Start with public capabilities. Use the free-text knowledge search with a short general mortgage question in Hebrew. Keep each returned source and effective date. Defined calculators are hypothetical calculations, not live bank offers or a personal recommendation.

Public guides and calculators also have Markdown representations. Request Accept: text/markdown or use the linked Markdown file. Calculator Markdown describes inputs and limitations; use the calculation tool for computed results.

Discovery

• API catalog — the two public services and protected Office/Customer descriptions and OAuth metadata. Protected services require activation and authorization; a catalog entry does not prove availability, and an inactive route may return 404.
• MCP server card — draft discovery format.
• Agent skills index — draft discovery format.
• Full public reference — public text only.
• Security contact.

Private account connections

Office access is authorized by a signed-in staff member. Registered clients and explicitly enabled Client ID Metadata Documents (CIMD) describe clients; metadata does not grant access. Legacy Customer personal projections and screening remain disabled.

The protected resource advertises its authorization server in its WWW-Authenticate response. Use the advertised OAuth metadata, PKCE and exact resource value. Store credentials privately, respect revocation and never infer account access from an email address or a report token.

Office authorization server metadata. Availability depends on the configured protected service; public analysis does not create an Office account.

Public discovery interface status runs bounded checks from your device and shows their time. It does not verify report analysis, private connections or overall FINLY health.

Tool calls support server-side agents and explicitly approved browser origins. Arbitrary browser-origin CORS is not enabled; readable discovery metadata does not authorize cross-origin tool calls.

Customer monitoring and advisor handoff

Status: local implementation awaiting deployment and activation. This page is not evidence that these tools are live or published in the MCP Registry. Monitoring requires AGENT_CUSTOMER_MONITORING_ENABLED; webhook delivery additionally requires AGENT_CUSTOMER_WEBHOOKS_ENABLED. Discover enabled tools and scopes from the protected service after activation.

Use the advertised authorization server, PKCE S256 and the exact full /mcp/customer resource. The issuer's /public/agent-oauth/authorize endpoint directs Customer requests to /portal/agent/connect on the configured customer portal origin. The authenticated person selects exactly one case, scopes and an expiry of up to 30 days, then explicitly approves. They can list and revoke connections at /portal/agents. An email address, client metadata or public report capability is not portal authority.

• watch_refinance_opportunities, get_refinance_watch, list_refinance_watch_events and cancel_refinance_watch create, inspect, read events and cancel an authorized watch.
• request_advisor_handoff creates an office callback task; get_advisor_handoff reads its state. requested does not mean the advisor has acted.
• register_refinance_webhook validates an approved HTTPS event destination.

For a grant containing one case, case_id may be omitted when creating a watch or handoff; the server resolves it from the grant. The token response does not enumerate cases. Reuse the same idempotency_key for the same request. A watch without an active advisor baseline returns pending_advisor_baseline. An event invites professional review; it is not a savings or mortgage-change promise.

Attaching a result also requires the separately selected customer:attach_report_context scope; this is not an additional tool. Supply the private operation capability in analysis_context in the handoff request body, never a URL. FINLY stores the verified analysis result encrypted, without the PDF or recovery token. Access ends at the earlier of grant expiry and 30 days after attachment; cleanup jobs remove expired results. Advisor reads require current grant and sharing authority and are audited. Revocation and case erasure govern access and removal; they cannot erase copies already delivered to the agent.

Webhook destinations come from immutable approved registered-client or CIMD metadata and must pass an HTTPS challenge. Signed bounded events contain event/watch identifiers, time and review reasons, without names, report content, balances or rates. Keep the signing secret private and deduplicate delivery by event_id. Events remain accessible for up to seven days; cleanup jobs remove expired events. Revocation or expiry blocks new access and deliveries, but does not cancel an office task already created. See the privacy policy for recipients and retention.

Hand over to a person

Share the FINLY analysis page when the user wants to continue in the browser. The referral marker is optional and carries no personal data. Never add it to MCP or REST tool URLs.

Review the privacy policy and terms. FINLY does not promise savings or a bank approval.