# Connect your AI assistant to Expense: the MCP server

Expense speaks the Model Context Protocol: connect any MCP client (Claude, ChatGPT, Gemini CLI, and others) and it can capture receipts from photos and PDFs, log drives at the IRS rate, answer spending questions from your data, build and export reports, and reconcile bank statements. Connecting is signing in with your Expense account via OAuth; there are no API keys.

The base MCP server address is https://expense.labnotes.org/mcp (Streamable HTTP + OAuth). All connections use OAuth: the first connection opens a sign-in flow to your Expense account; there are no API keys.

## Tools

| Tool | Writes | What it does |
| --- | --- | --- |
| `capture_receipt` | yes | Capture a receipt from an image or PDF (file data or URL): extraction pipeline, stores the image, creates the expense. |
| `log_mileage` | yes | Log a driving trip from ordered stops; geocodes, routes, and prices it at the IRS rate. One way unless the trip returns to its first stop. |
| `list_expenses` | no | Query expenses by date range, category, merchant, report, or type. |
| `expense_summary` | no | Totals and per-category breakdown: the "how much did I spend on X?" tool. |
| `list_reports` | no | Reports with expense counts and exact totals. |
| `create_report` | yes | Create a report (fails if the name exists). |
| `close_report` | yes | Close (or reopen) a report; closed reports refuse new expenses. |
| `add_to_report` | yes | Move an expense into an open report. |
| `export_report` | no | Render a report as a PDF (same layout as the web export) and return it base64-encoded. |
| `list_categories` | no | The account's categories; use these when categorizing. |
| `list_merchants` | no | Merchant names previously used, most recent first. |
| `get_settings` | no | Home address, the account's named locations (work, hospital), and the IRS mileage-rate table. |
| `reconcile` | no | Match a bank statement (CSV/QFX/OFX) against logged expenses; pure analysis, writes nothing. |

## Setup instructions

### Claude (claude.ai and Claude Desktop)

1. Go to claude.ai/customize/connectors
2. Click the + icon, then "Add custom connector"
3. Enter the server URL: https://expense.labnotes.org/mcp
4. Claude opens a browser to sign in to Expense; approve the connection

The connector also appears in Claude Desktop and Claude Code when signed in with the same Claude account.

### ChatGPT

1. Go to Settings > Apps > Advanced settings and enable Developer mode
2. Click "Create app" and enter the server URL: https://expense.labnotes.org/mcp
3. Select Developer mode from the Plus menu to use Expense in conversations

Requires a Pro, Plus, Business, Enterprise, or Education plan.

### Gemini CLI

1. Add to ~/.gemini/settings.json:

```json
{
  "mcpServers": {
    "expense": {
      "httpUrl": "https://expense.labnotes.org/mcp"
    }
  }
}
```

### Pi

1. Install the MCP adapter and restart Pi: pi install npm:pi-mcp-adapter
2. Add to .mcp.json (project) or ~/.config/mcp/mcp.json (global):
3. Ask for a tool: the first call opens the Expense sign-in, or run /mcp-auth expense.

```json
{
  "mcpServers": {
    "expense": {
      "url": "https://expense.labnotes.org/mcp",
      "auth": "oauth"
    }
  }
}
```

Pi has no built-in MCP client by design; pi-mcp-adapter is the community package that adds one.

### Oh My Pi (OMP)

1. Add to ~/.omp/agent/mcp.json (user) or .omp/mcp.json (project):

```json
{
  "mcpServers": {
    "expense": {
      "type": "http",
      "url": "https://expense.labnotes.org/mcp"
    }
  }
}
```

Or run /mcp add in a session. OMP opens the Expense sign-in when the server asks for auth; /mcp reauth expense re-approves later.

### Anything else

1. Any MCP client with Streamable HTTP transport works: point it at the server URL above.
2. The client discovers the OAuth flow automatically via /.well-known/oauth-authorization-server and opens the Expense sign-in; approve once and consent is remembered.

## Security

Connecting is OAuth 2.1 with PKCE: the assistant never sees your password, access tokens live one hour, refresh tokens rotate, and only hashes are stored. A connection only ever reaches your own account. Revoke it anytime in Settings → Agents & API (MCP). Delete a single token or disconnect the whole app.

For the browser-based in-page tools (WebMCP), and the app's own Insights page that answers questions about your spending with nothing connected, see [Expense: connect your AI assistant](https://expense.labnotes.org/ai.md).