API v1 · agent-friendly docs
Connect with AnythingMCP
Optional OpenAPI bridge: turn the curated BennyBooks OpenAPI surface into MCP tools when you cannot use native /api/mcp.
Prefer native MCP
For Cursor, Claude custom connectors, and most hosts, use Streamable HTTP at https://bennybooks.com/api/mcp instead (Guides → Connect Streamable HTTP MCP). Use AnythingMCP only when you need an OpenAPI→MCP bridge.
AnythingMCP imports our OpenAPI spec and generates MCP tools. Enable only the curated set (~12 tools) — not every operation. See MCP tool design for why.
Agent-efficient by default
OpenAPI is enriched at https://bennybooks.com/openapi.json with when/when-not descriptions, x-mcp annotations, and list default limit=50. Config: config/anythingmcp-bennybooks.yaml.
Localhost vs cloud AnythingMCP
Cloud AnythingMCP cannot fetch http://localhost. Use a public tunnel (ngrok / Cloudflare Tunnel) as Base URL + OpenAPI URL, deploy BennyBooks, or run self-hosted AnythingMCP locally. setup-anythingmcp.sh refuses cloud+localhost combinations.
Prerequisites
- BennyBooks account with an organization
- API token from Settings → MCP & agents (read and/or propose-write)
- AnythingMCP account (anythingmcp.com)
Setup
- In AnythingMCP: Connectors → New Connector → REST
- Base URL: https://bennybooks.com
- OpenAPI URL: https://bennybooks.com/openapi.json
- Auth: Bearer token → your bb_live_… token
- Import the spec — tools are named by OpenAPI operationId
- Expose only the curated tools listed below (disable create_note, list_notes, etc.)
- Point your MCP client at the AnythingMCP endpoint
Automated setup
Run pnpm verify:mcp to confirm catalog/OpenAPI/yaml sync. Then ./scripts/setup-anythingmcp.sh with ANYTHINGMCP_URL, ANYTHINGMCP_TOKEN, and BENNYBOOKS_MCP_TOKEN set. Still toggle optional tools off if AnythingMCP enables all operations.
Curated tools (enable)
| Tool | Scope |
|---|---|
| get_ontology | public |
| list_categories | read |
| list_transactions | read |
| get_transaction | read |
| get_dashboard_summary | read |
| search_receipts | read |
| list_connectors | read |
| import_revolut_csv | propose-write |
| list_pending_proposals | read |
| propose_categorization | propose-write |
| propose_journal_entry | propose-write |
| propose_receipt_link | propose-write |
| attach_note | propose-write |
Optional (keep off)
| Tool | Why off by default |
|---|---|
| get_ontology_context | Public JSON-LD @context only |
| get_ontology_ttl | Public ontology as Turtle (same graph as get_ontology) |
| sparql_ontology | Run a read-only SPARQL query over the static BennyBooks ontology graph |
| sparql_ontology_post | POST variant of sparql_ontology (application/sparql-query or form query=) |
| get_proposal | Fetch one proposal by id |
| get_receipt | Receipt metadata by id (not file bytes) |
| list_notes | Notes for a transactionId |
| create_note | Directly create a note without approval |
Full design notes: Connect → MCP tool design. Agent playbook: /skill.md.