Connect an MCP client and manage authorizations

MCP connects a compatible external AI client to Boldo. It can read data, submit suggestions or make direct changes, depending on its authorization. The connection acts with your Boldo permissions in one organization.

Check access

Your plan must include MCP and AI, with AI enabled. Your member account needs AI access and MCP access. Sign-in method, SSO, two-factor and allowed-IP requirements also apply. The client service may use a different IP address from your browser.

An Administrator or Owner selects MCP level in member settings:

MCP level	Available actions
Read only	Read the information available to the member.
Read and suggest	Also submit change suggestions for review in Boldo.
Read, suggest and write	Also make direct changes, when the organization allows them and the connection was given write access.

AI access level is separate: Level 1 - Platform only gives schema and documentation tools. Level 2 - Business data enables business-data tools within the member's permissions. A higher MCP level does not bypass this restriction.

The MCP administration page requires Editor access or higher. An authorized Viewer can still connect through a compatible client and the public connection documentation. Direct writes require Editor access or higher and the relevant business permissions.

Connect the client

1. Open /mcp-doc on your Boldo environment, or follow Organization settings > MCP > MCP documentation when available.
2. Copy the environment's endpoint. In production, it is https://app.boldo.io/api/mcp.
3. Add a remote MCP server in your client using Streamable HTTP, this URL and the client's OAuth connection flow.
4. Sign into Boldo with a method accepted by the organization.
5. On Connect an MCP client, check the organization, even if only one is eligible. Each one shows the most you are allowed there.
6. Under Access level, click how far this connection goes: Platform, Read, Suggest or Write. Steps above your rights are locked, and Write is never preselected. Then click Authorize.
7. Return to the client and load its tools. Start with a limited read of a known asset or type.

You can give a connection less than your rights allow, for example Read for a strictly read-only client. Boldo applies the lowest of this choice and your current rights on every request: if an administrator lowers your rights, the connection follows at once; raising them restores access only within your previous consent. Reconnect and consent again to exceed that saved level.

Do not append an organization slug to the endpoint. OAuth binds the organization to the connection; a v1 API key cannot replace it. Use the connection examples displayed by Boldo for your client, whose menus and configuration formats may vary.

Suggest or change data

Read tools cover schemas, documentation, assets, relationships, visualizations, processes, impact analyses and scenarios, according to access. Read tools can also count assets or distinct values, sum a numeric property and calculate its average. Ask for a total or a breakdown by one or two dimensions. Multi-valued groups can overlap, so adding their results may differ from the overall total.

MCP also provides resources at boldo://docs/getting-started and boldo://docs/metamodel-overview.

Ask the client what you have to do: it reads the To do and My suggestions tabs of your Home. Each category comes with its total, its first assets and a link to open it in Boldo. Incomplete requires repository quality. To attest also requires real data. Pass scenarioId to read the worklist in a scenario.

When repository quality is active, an Administrator or Owner can also ask for the organization's quality overview. It gives freshness and completeness by type and owner, owners who left or cannot read their assets, and pending suggestions, including those on assets without an owner. Pass scenarioId for the scenario’s overview, which omits dedicated freshness indicators. Checks for departed owners and owners without read access still use real data. The overview is read-only: act from the quality reports or the links it returns.

A client can request Boldo’s brand guidelines, including colors, fonts and logo, even with Platform access. Ask it to use them for a report or chart. Your chosen style takes precedence; check the result, as clients may apply the guidance differently. Boldo is the data source, not the report’s author.

With suggestions enabled, ask the client to suggest an asset creation, property correction, relationship change or asset archive. Review these through the suggestion workflow in Boldo. You can ask the client to list an asset’s suggestions and withdraw a pending one you submitted. A creation suggestion can include up to 50 relationships to existing assets or other pending creation suggestions. Each relationship also counts toward the shared write budget. Submitting a suggestion does not apply the suggested change.

You can also ask the client to correct a pending creation suggestion you authored or are allowed to create. It can update its name, properties, domains, owners and note without withdrawing it first. To correct its relationships later, submit or withdraw the corresponding relationship suggestions. Review the resulting creation suggestion in Boldo before creating the asset.

Direct writes require all three authorizations:

1. An Administrator or Owner enables Allow direct writes via MCP in Organization settings > MCP.
2. Your member's MCP level is Read, suggest and write.
3. You choose Write when connecting the client.

When authorized, the client can create, update, archive and restore assets, and create, update or remove relationships. It can also attest assets you own in real data when repository quality is active, and accept or reject pending suggestions you are allowed to review. Asset creation and updates, attestations and suggestion reviews support batches of up to 50 items. A suggestion whose value changed since it was submitted is skipped, never overwritten, and accepting an archive suggestion requires an explicit confirmation. Read each result, including skipped items; a successful response can contain partial failures.

Direct writes take effect immediately

These tools do not open an AI proposal card in Boldo’s chat. Any confirmation belongs to your external client. State the intended scope and context, then check the saved result in Boldo. An interrupted response does not prove that nothing changed.

Suggestions and direct writes share a limit of 100 elements per 60 seconds per member and organization. A batch counts once per item. Respect the returned retry delay. If the write budget cannot be checked, writes and suggestions are temporarily unavailable; reads remain available.

Work in a scenario

Ask the client to list scenarios with listScenarios. Choose an accessible, active, ready scenario and provide scenarioId on every relevant tool call, including getScenarioDiff. Without it, a call targets real data; there is no persistent MCP switch into a scenario.

Compatible reads, suggestions and writes use this scenario context. Scenario availability still depends on your plan and permissions. MCP cannot create, apply or abandon scenarios. Use the scenario interface for those actions.

Remove a connection

For your own connection, open Account settings > Security > Connected apps. Find the client and organization, click Revoke, then confirm with Revoke in Revoke access.

As an Administrator or Owner, open Organization settings > MCP > Connected agents. Find the client and member, click Revoke, then confirm in Revoke agent access. Other connections remain separate.

Revocation stops the connection at once, including access tokens already issued, and requires fresh consent to reconnect. Membership, permissions and MCP eligibility are checked again on requests. Disabling the organization's direct-write setting blocks subsequent direct writes; it does not undo changes or disable permitted suggestions.

Diagnose a connection

Symptom	Check
Organization missing from the connect screen	Plan, AI activation, AI/MCP permission and accepted sign-in method.
Authentication refused	Session, token expiry, SSO, two-factor and IP requirements.
Only schema tools available	The member's AI access level.
Empty business results	Organization, scenario and business permissions.
Suggestion tool unavailable	Business-data AI access, an MCP level that allows suggestions and the access chosen when connecting.
Write tool unavailable	Organization setting, member MCP level and type, the access chosen when connecting and business permissions.
Rate limit reached	Respect the retry delay; the request limit and write-element limit are separate.

MCP requests are limited to 60 per 60 seconds per token. This differs from the v1 API limit shared by an organization. Ask an administrator to correct access settings rather than disabling organization protections.