# Zahlenwerk

> An LP / family-office data layer: investor report ingestion and extraction,
> portfolio positions (fund LP stakes, direct equity, SAFEs, option grants,
> SPVs), a company and person directory with document generation, and
> double-entry bookkeeping. EU data residency throughout.

Zahlenwerk is agent-accessible over the Model Context Protocol. There is no
separate REST API: the MCP endpoint is the machine interface.

## Connecting

MCP endpoint (streamable HTTP): https://app.zahlenwerk.studio/api/mcp

Two ways to authenticate, both scoped to one user and revocable at any time:

1. OAuth 2.1 with dynamic client registration — for interactive clients such
   as Claude. Discovery documents:
   - https://app.zahlenwerk.studio/.well-known/oauth-protected-resource
   - https://app.zahlenwerk.studio/.well-known/oauth-authorization-server
   PKCE (S256) is required; `plain` is rejected.
2. A personal access token — for CI, cron, or scripts that cannot open a
   browser. Create one at https://app.zahlenwerk.studio/settings/mcp and send it as
   `Authorization: Bearer <token>`.

Either way the connection acts as one user, under that user's own row-level
permissions, and never more: an owner can cap a member's agent access below
their own, and a connection can be narrowed to specific features.

## Conventions worth knowing before you call anything

- Teams: a user may belong to several, and each team's data is isolated. If a
  tool returns `action_required: "select_team"`, ask the user which team and
  pass that `organization_id` on every subsequent call. Do not guess.
- Writes are separate tools, marked [write] below. In the web app they require
  explicit user confirmation.
- Large files: upload via the signed-URL flow (`create_report_upload_url` →
  PUT the bytes → `finalize_report_upload`), never base64 in a tool argument.
  Files that are kept rather than parsed — deeds, contracts, resolutions —
  attach to a position the same way (`create_position_file_upload_url` →
  PUT → `attach_position_file`).
- Prefer slim reads. `get_report` returns metrics plus a company count by
  default; page through `list_report_companies` instead of inlining whole
  portfolio tables.
- Resources (`zahlenwerk://collection/{id}`, `zahlenwerk://report/{id}`,
  `zahlenwerk://book/{id}`) are browsable and cost nothing until opened.
  Prefer linking one over pasting a large table into an answer.

## Tools

Call `tools/list` for full descriptions and input schemas. Summary:

- add_entity_bank_account [write]: Record a bank account for a directory entity, so capital-call payments from that entity can be prefilled and a SEPA file generated.
- add_valuation [write]: Add a valuation point to a position.
- archive_entity_bank_account [write]: Retire a bank account, or bring a retired one back (restore:true).
- code_transaction [write]: Assign a bank transaction to an account, and optionally a tax code and cost centre.
- convert_note [write]: Convert a convertible note or SAFE into equity.
- create_collection [write]: Create a new report collection for a fund.
- create_direct_equity_position [write]: Create a direct-equity position (shares held outside a fund or SPV).
- create_directory_entity [write]: Create a legal entity (GmbH, AG, fund, trust, foundation …) in the user's directory.
- create_directory_person [write]: Create a natural person in the user's directory — a director, shareholder, beneficial owner or contact.
- create_fund_lp_position [write]: Create a fund LP position by hand (no quarterly report needed).
- create_option_grant [write]: Create an option / RSU / VSOP grant (ESOP).
- create_safe [write]: Create a SAFE or convertible note position.
- create_share_account [write]: Create an employee share-plan account (e.g.
- create_spv [write]: Create an SPV (single-deal vehicle) position into one company.
- delete_position_event [write]: Delete one position event.
- delete_report [write]: Delete one report from its collection, e.g.
- delete_vesting_schedule [write]: Remove a grant's vesting schedule, e.g.
- find_collection_by_fund_name: Case-insensitive lookup of an existing collection by fund name.
- generate_dossier: Build a KYC dossier for a directory entity: a ZIP that bundles a letterhead-headed overview document (the entity plus its board members and beneficial owners, each with their KYC profile and a checklist of required documents) together with every uploaded file on record.
- generate_letter: Write a full business letter on a directory entity's letterhead and return it as a downloadable Word (.docx) and/or PDF file, and optionally as a Google Doc link.
- generate_letterhead: Generate a Word (.docx) letterhead + footer for a directory entity and return it as an attachable file.
- generate_person_letter: Write a full business letter on a directory PERSON's letterhead and return it as a downloadable Word (.docx) and/or PDF file.
- generate_person_letterhead: Generate a Word (.docx) letterhead + footer for a directory PERSON and return it as an attachable file.
- get_aircraft: Everything recorded about one aircraft, by tail number: the master data
- get_collection: Fetch a single report collection by id, including all its reports.
- get_company: Fetch one company and every position the user holds in it (across instrument types).
- get_cost_centres: Spend grouped by cost centre for a book's period, plus the grand total and how much is unassigned.
- get_position: Fetch one position by id with its full valuation history.
- get_profit_and_loss: Profit & loss for a book's period: revenue and expense lines with their movement, plus totals and net result.
- get_report: Fetch a report by id.
- get_tax_report: VAT / GST detail for a book: per-transaction taxable amounts and tax by code, with totals.
- get_trial_balance: Trial balance for a book: opening balance, period debits and credits, and closing balance per account.
- import_flight_hours [write]: Write the monthly readings from the attached flight-hours PDF into the
- import_flight_log [write]: Write the attached monthly flight log: the month's totals and every
- list_aircraft: List the team's aircraft — tail number, type, owning company — each
- list_books: List the bookkeeping books (one per legal entity and period) in the current team.
- list_collections: List the user's investor/LP report collections (one per fund) with each collection's reports.
- list_directory_entities: List the directory entities available for letterhead generation.
- list_directory_people: List the directory persons available for letterhead generation.
- list_entity_bank_accounts: List the bank accounts recorded for a directory entity — the accounts that entity pays FROM, used as the debtor when a SEPA capital-call file is generated.
- list_position_events: Return the full cashflow / state-change event series for a position, oldest first.
- list_positions: List the user's positions.
- list_report_companies: Paginated, server-side filtered/sorted portfolio companies for a report.
- list_transactions: Bank transactions in a book, filtered and paginated server-side.
- list_valuations: Return the full valuation history for a position, newest first.
- plan_photo_filing: Say which record each folder of an attached photo delivery should go
- portfolio_summary: Return a one-shot snapshot of the user's private-market portfolio.
- preview_flight_hours_import: Read the monthly flight-hours PDF the user attached to this message and
- preview_flight_log_import: Read the operator's monthly FLIGHT LOG for one aircraft that the user
- record_cashflow [write]: Record a distribution / dividend / exit cashflow on a position.
- record_contribution [write]: Record money the investor PAID IN on a position: a capital call, a purchase, or a fee.
- record_position_event [write]: Record any event on a position: a cashflow or a share movement, with its full payload.
- set_aircraft_master [write]: Record master data on one aircraft — the fields the user has established
- set_position_holder [write]: Attribute a position to the Directory record that holds it: an entity (a GmbH, a trust) or a natural person.
- set_position_paying_account [write]: Choose which of the holder entity's bank accounts a position's capital calls are paid from.
- set_vesting_schedule [write]: Create or edit the vesting schedule of an option / RSU / VSOP grant (one schedule per grant).
- update_collection [write]: Rename a collection.
- update_position [write]: Set a position's cost_basis, entry_date and/or metadata fields: notes, settlement (net | cash_exercise), shares, shares_as_of, price_per_share, plan_name, share_account_position_id.
- update_position_event [write]: Edit one position event in place.

## Not available

- There is no public REST or GraphQL API, and no OpenAPI document.
- There are no outbound webhooks yet. Poll `get_report` after an upload;
  it returns `recommended_next_poll_seconds` — honour it rather than
  polling in a tight loop.
- Rate limits apply per connection. On HTTP 429, honour `Retry-After`.

## Contact

https://app.zahlenwerk.studio