# FinDB Analysis MCP Server

A read-only [Model Context Protocol](https://modelcontextprotocol.io/) server for the FinDB demo database, hosted as an Appwrite Function. It exposes customer, account, card, and transaction analysis 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:

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

### Smoke test

Initialize the MCP server directly over HTTP:

```bash
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:

```bash
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 analysis 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 | `financial-analysis` | 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.