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

Setting	Value
MCP endpoint	https://6a73369c003d9823a215.fra.appwrite.run/
Authentication	Bearer token
Bearer token	test-string-123

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.

Tool	Arguments	Description
portfolio_summary	None	Dataset counts, balances by currency and account type, transaction volume by status, and the covered date range.
list_customers	kyc_status?, country?, limit?, offset?	Lists customer profiles, optionally filtered by KYC status or country.
customer_overview	customer_id	Returns a customer's profile, accounts, cards, and recent transactions.
account_statement	account_id, from_date?, to_date?, limit?	Returns account details, transactions, and period totals. Defaults to the last 30 days.
spending_by_category	account_id?, customer_id?, from_date?, to_date?, flow?	Aggregates completed debit spending or credit income by category.
monthly_cash_flow	account_id?, customer_id?, months?	Reports monthly inflow, outflow, and net cash flow for up to 24 months.
search_transactions	account_id?, category_id?, status?, transaction_type?, min_amount?, max_amount?, from_date?, to_date?, limit?	Searches transactions using optional filters, newest first.
list_accounts	customer_id?, account_type?, status?, limit?	Lists accounts, optionally filtered by customer, type, or status.

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:

Prompt	Expected tool
"Give me a high-level summary of the FinDB portfolio, including balances by currency and transaction counts by status."	portfolio_summary
"List the first 10 customers whose KYC status is verified."	list_customers
"Show me the complete customer overview for cust-001, including accounts, cards, and recent transactions."	customer_overview
"Generate an account statement for acc-001 covering the last 30 days."	account_statement
"Break down all completed debit spending by category across the bank."	spending_by_category
"Show the monthly inflow, outflow, and net cash flow for customer cust-001 over the last 12 months."	monthly_cash_flow
"Find the 10 most recent completed debit transactions for acc-001 with amounts between 20 and 500."	search_transactions
"List the first 20 active savings accounts."	list_accounts

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.

Header	Requirement	Example
Authorization	Required when MCP_AUTH_MODE=bearer	Bearer test-string-123
Content-Type	Required	application/json
Accept	Recommended	application/json, text/event-stream
MCP-Protocol-Version	Optional	2025-06-18

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

Path	Purpose
src/main.py	Appwrite Function entrypoint.
src/app.py	FinDB tools and TablesDB queries.
src/appwrite_mcp/	Bearer authentication and buffered MCP-over-HTTP transport.
appwrite.config.json	Function, database, tables, columns, indexes, and relationships.

Appwrite configuration

Setting	Value
Runtime	Python 3.14
Entrypoint	src/main.py
Build command	pip install -r requirements.txt
Execute permission	any (the Bearer token protects the HTTP endpoint)
Function scopes	databases.read, tables.read, rows.read
Timeout	30 seconds

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

Variable	Required	Default / demo value	Description
MCP_SERVER_NAME	No	findb-reporting (live demo: finance-mcp)	Name returned by MCP initialization.
MCP_AUTH_MODE	No	none (live demo: bearer)	Set to bearer to require HTTP Bearer authentication.
MCP_AUTH_TOKEN	When using Bearer auth	Live demo: test-string-123	Shared Bearer token, compared in constant time.
FINDB_DATABASE_ID	No	findb	Appwrite TablesDB database ID.
MCP_TOOL_TIMEOUT	No	25	Soft request deadline in seconds, below the 30-second function limit.
MCP_DEBUG	No	Unset	Set to 1 to expose tool exception details and log unusual Accept headers.
APPWRITE_API_KEY	No	Unset	Local-development fallback when the dynamic x-appwrite-key is unavailable.

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.