open-bp MCP: reference for agents

Public tool contracts, workflow and financial conventions. This page contains no project data and does not replace authentication.

Read the Markdown version Tool JSON schemas Connection guide

Connect to the server

https://open-bp.com/api/mcp

Streamable HTTP transport, POST requests using JSON-RPC. The client negotiates the protocol with initialize, then discovers tools with tools/list. Every request must be authenticated.

OAuth uses protected resource discovery and PKCE. A personal key uses the Authorization header with Bearer. Never put keys or tokens in URLs, model requests or logs.

OAuth resource metadata

Agent workflow

Authenticate the connection using OAuth or a private key. The public catalogue describes contracts; it grants no access to projects.
Call tools/list after authentication to discover only the tools authorized for the connection.
Read project_get and project_context before modifying a project. Use the identifiers, units, periods and sources returned by the server.
Prepare a draft using project_edit_draft or project_update with commit=false. Recalculate with project_calculate and present differences.
Save only after an explicit request, using project_save or commit=true and the expected version. A version error requires rereading the current data.
Handle sharing, account and billing operations separately. Check their parameters and request confirmation before calling them.

Conventions and checks

Amounts are in euros. Decimal values in financial assumptions are strings; rates are fractions and calculation periods are monthly.
Keep source statuses missing, example, estimate and confirmed. Do not invent amounts, documents, sources or commercial evidence.
Permissions and quotas are checked again on the server for every action. The admin role requires a verified incwo account; a token does not create that role.
The connection remains bound to the open-bp session that authorized it. OAuth renewal does not extend that session; reconnect after it expires.
Exports use the saved version. Calculations describe assumptions; they do not provide professional validation of the business plan.

MCP tool catalogue

68 contracts are described here. After connection, tools/list returns only tools authorized for your identity and permissions.

To read one schema, add the tool parameter to the JSON catalogue, for example:

/agents/catalogue.json?tool=project_update

Tool	Required permission	Action and conditions
`account_delete`	`account`	Schedule or cancel account deletion after confirming its email. Requires a session created less than ten minutes ago and checks Stripe commitments.
`account_export`	`account`	Export personal data and all owner projects as private JSON, without connection secrets.
`account_get`	`account`	View the account, available connections and any scheduled deletion.
`account_link_provider`	`account`	Prepare linking Google or incwo to the account. Open the link and confirm with the provider to complete the link.
`account_revoke_sessions`	`account`	Sign out other account sessions. Their MCP keys are also deleted.
`account_sign_out`	`account`	Sign out the session that authorised the assistant and revoke its active keys and authorisations. Requires explicit confirmation.
`admin_accounts`	`admin`	Search accounts and view their permissions and latest grants. Restricted to verified incwo accounts.
`admin_grant_subscription`	`admin`	Grant a temporary subscription with a duration and audit history, without a Stripe payment. Restricted to verified incwo accounts.
`admin_revoke_subscription`	`admin`	Remove a temporary grant and restore billed permissions. Restricted to verified incwo accounts.
`assistance_history`	`read`	Read drafting proposals, reviews and their quotas.
`assistance_request`	`write`	Request drafting or a review from OpenAI after consent, with a quota and retry identifier. Texts remain proposals.
`assumption_update`	`write`	Edit the status, source and note of an existing assumption. Confirmation requires an origin or a note. commit=true saves the change.
`billing_cancel_change`	`billing`	Cancel a scheduled plan change.
`billing_checkout`	`billing`	Create a Stripe link after selecting a plan, billing interval and explicitly accepting the terms. The link does not prove payment.
`billing_confirm_change`	`billing`	Confirm a still-valid plan change preview after agreement on the amount and date.
`billing_portal`	`billing`	Open the Stripe portal for cards, invoices and cancellation.
`billing_preview_change`	`billing`	Calculate the prorated amount and date of a plan change without confirming it.
`billing_refresh`	`billing`	Reconcile the subscription with verified Stripe invoices.
`chat_action_confirm`	`write`	Confirm a specific action prepared by the chat. Checks the session, original permissions, version and draft fingerprint; retries do not repeat completed actions.
`chat_actions_list`	`read`	View actions prepared by the chat for your session, their data and status.
`chat_history`	`read`	Read private chat exchanges and the assistance quota.
`chat_send`	`write`	Send a message and draft data to OpenAI, with consent and a quota. Returns a checked proposal without saving the project.
`comment_add`	`write`	Add a comment to a section and the current project version.
`comment_resolve`	`write`	Mark a comment as resolved or reopen it, according to account permissions.
`comments_list`	`read`	Read private project comments with pagination.
`cost_estimate`	`read`	Calculate an expense using the supplied method and values, without inventing an amount.
`costs_list`	`read`	View available expenses and estimation methods.
`expense_estimate_apply`	`write`	Apply a numerical estimate to an expense, retain its method and source, and recalculate. commit=true saves the change.
`expenses_add_standard`	`write`	Add selected expenses from the catalogue, without invented amounts or duplicates. Amounts remain to be entered. commit=true saves the change.
`expenses_remove`	`write`	Delete an explicitly specified row and remove its scenario overrides. commit=true saves the change.
`expenses_upsert`	`write`	Add or edit a complete assumption row with its stable identifier. commit=true saves the change.
`invitation_accept`	`write`	Accept an invitation matching the account’s verified email address.
`invitations_list`	`read`	List invitations for the account’s verified email address.
`language_set`	`read`	Choose the language of tools and replies for this MCP connection. Data and financial rules stay the same.
`mcp_connection_create`	`access`	Create an MCP key after explicit confirmation. Can only delegate the current connection’s permissions. Store the returned key in private configuration.
`mcp_connection_revoke`	`access`	Revoke an MCP key belonging to the account after explicit confirmation.
`mcp_connections_list`	`access`	List the account’s MCP keys and permissions without displaying secrets.
`monthly_evolution_set`	`write`	Replace or remove the progression and overrides of the specified monthly field only. A zero override remains explicit. commit=true saves the change.
`oauth_connection_revoke`	`account`	Remove an assistant’s OAuth authorisation and revoke its access and refresh tokens.
`oauth_connections_list`	`account`	List assistants authorised through OAuth and their permissions, without connection secrets.
`payroll_remove`	`write`	Delete an explicitly specified row and remove its scenario overrides. commit=true saves the change.
`payroll_upsert`	`write`	Add or edit a complete assumption row with its stable identifier. commit=true saves the change.
`portfolio_list`	`read`	View client dossier progress with the Cabinet view and pagination.
`project_archive`	`write`	Archive or reactivate a project owned by the account, checking its version and quota.
`project_calculate`	`read`	Recalculate a draft and compare its scenarios using the financial engine.
`project_context`	`read`	Read field paths, units, periods and results to edit the correct project.
`project_create`	`write`	Create a project from a template. The server checks the active project quota.
`project_edit_draft`	`write`	Edit a draft and recalculate results without saving. Paths and units are provided by project_context. To save, use project_save with the expected version.
`project_export`	`read`	Export the saved version as PDF, Word, Excel, PowerPoint, CSV (ZIP archive), OpenDocument text or spreadsheet, or offline HTML. Returns a private resource; subscription permissions are checked.
`project_get`	`read`	Read the project’s saved data, version and permissions.
`project_save`	`write`	Save all project fields, sources, expenses, monthly profiles, scenarios and dossier. Requires the expected version and creates a new revision.
`project_update`	`write`	Edit only the requested project fields. Financial groups are merged; lists are replaced. commit=false proposes a draft; commit=true saves with version checking.
`projects_list`	`read`	Search private and shared projects, including archives, with pagination.
`revenues_remove`	`write`	Delete an explicitly specified row and remove its scenario overrides. commit=true saves the change.
`revenues_upsert`	`write`	Add or edit a complete assumption row with its stable identifier. commit=true saves the change.
`revision_compare`	`read`	Compare two saved versions or a draft with a version: assumptions, sources, scenarios, dossier and calculated results.
`revision_get`	`read`	View data and results from a saved project revision.
`revision_restore`	`write`	Restore a complete saved revision by creating a new version without overwriting history.
`revisions_list`	`read`	List private project revisions with version-based pagination.
`scenario_remove`	`write`	Delete the explicitly specified scenario, including a legacy saved scenario. commit=true saves the change.
`scenario_upsert`	`write`	Create or edit a complete scenario while retaining the initial forecast. Checks quotas and recalculates the comparison. commit=true saves the change.
`share_invite`	`write`	Invite an editor or reader to the project, checking quotas. This action sends no email.
`share_revoke`	`write`	Remove a project invitation or access for its owner.
`shares_list`	`read`	List project invitations and access for its owner.
`subscription_get`	`read`	View the effective plan, paid permissions, quotas and scheduled change.
`template_get`	`read`	View a template, its activities, questions and assumptions.
`template_prepare`	`read`	Prepare a project from a template and supplied values without saving.
`templates_list`	`read`	List business templates and their versions. Examples are fictional.