API v1
MCP tool design
How BennyBooks shapes MCP tools for clean, token-efficient agent use.
Agents only see tool names, descriptions, and schemas. Vague or bloated surfaces cause wrong calls and wasted context. BennyBooks ships a curated catalog rather than a raw OpenAPI dump.
Principles
- Curate ~12 tools — disable redundant operations in your MCP bridge
- verb_noun names (list_transactions) matching OpenAPI operationId
- Descriptions cover what, when to use, and when not to use
- Put constraints in the schema (enums, date format, limits)
- Lean lists — default limit=50; prefer get_transaction over list_notes
- Writes are proposals only until a human approves (recorded in Log)
- Prefer categoryCode over display names
- x-mcp annotations: readOnlyHint, destructiveHint, idempotentHint, openWorldHint
Default expose set
| Tool | Scope | Role |
|---|---|---|
| get_ontology | public | Get ontology |
| list_categories | read | List categories |
| list_transactions | read | List transactions |
| get_transaction | read | Get transaction |
| get_dashboard_summary | read | Dashboard summary |
| search_receipts | read | Search receipts |
| list_connectors | read | List connectors |
| list_pending_proposals | read | List pending proposals |
| propose_categorization | propose-write | Propose categorization |
| propose_journal_entry | propose-write | Propose journal entry |
| propose_receipt_link | propose-write | Propose receipt link |
| attach_note | propose-write | Attach note (proposal) |
Workflows
- Categorize — list_categories → list_transactions(status=uncategorized) → propose_categorization
- Investigate — get_transaction (notes + receipts) → search_receipts if needed
- Month-end — get_dashboard_summary → chase uncategorized / receipt_missing / proposals / connectors
Audit trail
Propose-write tools are audit-logged. Humans see Approvals for decisions and Log (/log) for history. Agents have no read API for Log in v1 — see Audit Log guide.
Source of truth
lib/mcp/tool-catalog.ts drives OpenAPI enrichment, AnythingMCP yaml, and /skill.md. Repo doc: docs/MCP.md.
Native Streamable HTTP MCP on this origin is not required for v1 — AnythingMCP (or a future small MCP server) wraps the same curated surface.