FinDB Reporting MCP Server

FinDB Reporting MCP Server

A read-only Model Context Protocol server for the FinDB demo database, hosted as an Appwrite Function. It exposes customer, account, card, and transaction reporting tools over stateless Streamable HTTP.

The server uses the official Python MCP SDK (mcp==2.0.0) and reads FinDB through Appwrite's TablesDB API. Monetary totals are grouped by currency (USD, EUR, or GBP) and are never converted.

Live demo

The token is intentionally public because this endpoint serves demo data. Do not reuse it for a production deployment.

Connect an MCP client

Add this to an MCP client that supports Streamable HTTP, such as Cursor or Claude Desktop:

{
  "mcpServers": {
    "finance-mcp": {
      "url": "https://6a73369c003d9823a215.fra.appwrite.run/",
      "headers": {
        "Authorization": "Bearer test-string-123"
      }
    }
  }
}

Smoke test

Initialize the MCP server directly over HTTP:

curl -sS -X POST \
  -H "Authorization: Bearer test-string-123" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0.0"}}}' \
  https://6a73369c003d9823a215.fra.appwrite.run/

Call the portfolio summary tool:

curl -sS -X POST \
  -H "Authorization: Bearer test-string-123" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"portfolio_summary","arguments":{}}}' \
  https://6a73369c003d9823a215.fra.appwrite.run/

Available tools

All tools are read-only.

Dates accept YYYY-MM-DD or full ISO 8601 timestamps. Common demo IDs include cust-001 and acc-001. Pass either account_id or customer_id to scoped aggregation tools, not both. List limits are capped at 100.

Test prompts

After connecting the server to your MCP client, try these prompts to exercise each reporting tool:

To test multi-tool reasoning, try:

• "Find the first verified customer, retrieve their full overview, and summarize their accounts and most recent activity."
• "List all frozen accounts, then inspect each account's latest transactions and highlight anything unusual."
• "Compare cust-001's account balances, spending by category, and monthly cash flow. Keep currencies separate."
• "Give me an executive report of the portfolio, then identify which account types hold the largest balance in each currency."

Results depend on the current demo dataset, so exact values may change between deployments.

HTTP interface

POST /

Accepts MCP Streamable HTTP JSON requests. The server supports legacy handshakes and the modern 2026-07-28 protocol path.

Successful requests return JSON-RPC responses. Notifications return 202 with an empty body. Missing or invalid credentials return 401 with a JSON-RPC error.

OPTIONS /

Returns 204 with CORS headers.

GET / and DELETE /

Return 405. The Appwrite Function is stateless and does not provide long-lived SSE streams or sessions.

Project layout

Appwrite configuration

The function receives a dynamic Appwrite API key in the x-appwrite-key request header. Its permissions are limited by the configured read-only function scopes.

Environment variables

Appwrite supplies APPWRITE_FUNCTION_API_ENDPOINT and APPWRITE_FUNCTION_PROJECT_ID in the deployed function environment.

Implementation note

Appwrite Functions are short-lived request/response workers and do not run a Starlette lifespan. Consequently, MCPServer.streamable_http_app() cannot initialize its task group here. The adapter uses the SDK's buffered lower-level entry points (serve_one and handle_modern_request) instead. Keep mcp==2.0.0 pinned because those helpers are private APIs that may move between releases.

Do not name a source module server.py; Appwrite Open Runtimes already provides a top-level module with that name.