Workpapers MCP interface

The Workpapers machine interface accepts authenticated HTTP POST JSON-RPC requests. It implements initialize, tools/list, tools/call and ping; it is not a general REST API for every BeforeMay product. Obtain the configured MCP endpoint for your practice from support before connecting. The hosted function route ends in /functions/v1/mcp.

Create and protect a key

An Owner or Admin can create a key under Workpapers → Settings → Connections → API keys. Choose only the scopes the integration needs. Copy the key when it is first shown: the stored record contains a hash and the full key cannot be revealed later. Keep it in your integration's secret storage, not browser code, a repository or a client document.

Send it as Authorization: Bearer YOUR_PRACTICE_API_KEY, with Content-Type: application/json. Keys act as the practice, not the member who minted them. Review and revoke them independently when an integration or team member is no longer trusted.

Scopes and tools

tools/list returns the tools allowed by the presented key, including their input schemas. Scope checks also apply to calls made directly by name. Case ownership comes from the key's practice, not a caller-supplied practice ID.

First read request

Begin with initialize. The implementation answers with protocol version 2025-06-18 and server version 0.1.0 at this guide's source review.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": { "name": "practice-integration", "version": "1.0.0" }
  }
}

Then request tools/list and use its schema. For example:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "list_cases",
    "arguments": { "fy": "2025-26", "limit": 25 }
  }
}

These are request examples, not credentials or real client records. List tools that accept limit default to 25 and cap it at 100. The current schemas do not provide a pagination cursor; do not assume a capped response is the entire practice directory.

Build and download

flowchart TB
  accTitle: MCP build and delivered-file access
  accDescr: A scoped practice key starts a build subject to allowance and concurrency checks. Poll the run with backoff; only delivered output receives a temporary download link.
  K[Practice key: builds:write] --> C[Check key, practice, allowance and concurrency]
  C -->|Accepted| R[start_build returns run_id]
  C -->|Refused| X[Inspect error and resolve the cause]
  R --> B[Queued build and configured review stages]
  B --> P[list_runs with cases:read and backoff]
  P --> Q{Delivered output exists?}
  Q -->|No: still active| P
  Q -->|No: failed or cancelled| X
  Q -->|Yes| D[get_workpaper with workpapers:read]
  D --> L[Download current delivered copy within 300 seconds]
  class C,Q control

get_workpaper also checks that the run belongs to the key's practice. Delivery is identified by its output file, not merely a phase name or a successful HTTP response. An earlier draft is not exposed through this tool.

Call start_build with case_id and optional notes. Starting work can consume the practice's credits and build allowance. It returns a run reference; inspect list_runs with backoff rather than holding the request open or repeatedly starting builds. When the relevant run has a delivered workbook, call get_workpaper with run_id.

An unfinished run returns ready: false. A delivered file returns a link with expires_in_seconds: 300. Download before it expires or request another link. The integration cannot obtain a pre-delivery draft through this tool.

Upload a document

sequenceDiagram
  accTitle: MCP upload authorisation and confirmation
  accDescr: Authorisation reserves a document and a storage path. The integration uploads bytes directly to private storage, then confirmation verifies and hashes them before filing the document.
  participant I as Integration
  participant M as MCP server
  participant S as Private storage
  I->>M: upload_document(case_id, filename)
  Note over M: Check documents:write, practice ownership and upload rules
  M-->>I: document_id, upload_url, method, content_type
  Note over I,M: Authorised but not yet filed as build evidence
  I->>S: PUT file bytes with returned Content-Type
  S-->>I: Upload response
  I->>M: confirm_upload(document_id)
  M->>S: Read reserved file bytes
  S-->>M: File bytes or missing-file error
  alt Bytes arrived and confirmation accepted
    Note over M: Hash bytes server-side and file the document
    M-->>I: Confirmation result
  else Missing bytes or refused confirmation
    M-->>I: Error - resolve before starting a build
  end

1. Call upload_document with case_id and filename.
2. Read document_id, upload_url, method and content_type from the answer.
3. PUT the file bytes to that signed URL using the returned Content-Type.
4. Call confirm_upload with the same document_id and inspect its result.

Authorisation alone is not a filed document. Confirmation verifies the stored bytes and computes their hash server-side. A failed confirmation must be resolved before expecting the document to be evidence for a build. A repeated confirmation can report that the document is already filed; inspect state before resubmitting the whole upload.

Interpret failures

Tool answers contain a text content block whose text is JSON. Check both result.isError and the decoded value's error, not just HTTP success. Protocol errors use a JSON-RPC error object. Rate-limit refusals can include retry_after_seconds; wait rather than retrying continuously. Quota, scope and ownership refusals need a configuration or practice decision, not another build.

Metadata can include extracted merchant and amount values. A downloaded workbook can contain personal financial information. BeforeMay's outbound AI controls do not govern what your own integration subsequently sends to another service.