Developers

MCP server

Connect Claude, ChatGPT or another MCP client to your BMC account with OAuth, without copying tokens, and work with your data in natural language.

What it is

MCP (Model Context Protocol) is the standard an AI assistant uses to call external tools. The BMC MCP server exposes 55 tools on top of the API: look up invoices and contacts, prepare a signature envelope, see the tax position. The assistant only sees and does what the role of the connection allows, and BMC checks the permission on every call.

The full list, with the permission and access type of each tool, is in MCP tools. If you are not technical and want the steps for your assistant (ChatGPT, Claude, Gemini, Cursor, n8n…), go to Connect your AI.

Server URL

https://app.bm.consulting/mcp

The server uses the Streamable HTTP transport and OAuth 2.1 with PKCE. It also accepts a bmc_live_… token as an Authorization: Bearer header.

Requirements

  • API access enabled by BMC on your account. It is the same requirement as for creating tokens (Getting started). If you do not have it, write to plataforma@bm.consulting.
  • Be an owner or administrator of that account in the client area.
  • An MCP client that supports remote servers with OAuth.

How to connect

Claude (web and Desktop)

  1. Open Customize › Connectors and click Add custom connector.
  2. Paste the URL https://app.bm.consulting/mcp. If the dialog asks for the OAuth client, choose Register automatically.
  3. Click Add, then Connect. BMC opens in the browser for the authorisation step (see below).

On Claude Team and Enterprise an Owner adds the connector under Organization settings › Connectors and each member connects with their own account from Customize › Connectors. Claude Free allows one custom connector. Connectors on your account also appear in Claude Desktop.

Claude Code

claude mcp add --transport http bmc https://app.bm.consulting/mcp

Then run /mcp inside Claude Code, choose bmc and click Authenticate.

Other MCP clients

Point the client at https://app.bm.consulting/mcp. It must support:

  • OAuth 2.1 with the authorisation code flow and PKCE S256 (the plain method is rejected).
  • Dynamic client registration as a public client (token_endpoint_auth_method: "none").
  • A redirect URI of https://… (exact match) or loopback (http://127.0.0.1:<port>/…, http://[::1]:<port>/… or http://localhost:<port>/…, any port).
  • The resource=https://app.bm.consulting/mcp parameter (RFC 8707).

The client discovers the rest on its own: the server answers 401 with the address of its metadata (/.well-known/oauth-protected-resource/mcp) and from there the client reaches the authorisation server (/.well-known/oauth-authorization-server).

The authorisation step

  1. Sign in to BMC with the sign-in link sent to you by email (open it in the same browser).
  2. Choose the company: the ones you administer and that have API access enabled are listed. Each connection reaches a single company; for several, use a token (below).
  3. Choose the role of the connection:
    • Analyst: read only, for everything your account can see.
    • Operator: ordinary read and write (create, update, delete), without critical actions such as issue, send, submit or void. Credentials and webhooks stay read only: a connection cannot create others.
    • Custom: permission by permission, with the same editor as credentials. It is the only way to grant the Full level and critical actions.
  4. Optional: an expiry (7, 30, 90 or 365 days, or none) and whether personal data is visible or masked (Authentication).
  5. Confirm. The client is connected.

The access token lasts 1 hour and the refresh token 30 days, and the client renews them on its own. Neither outlives the expiry of the connection.

What each role can do

RoleReadModify dataCritical actions
AnalystYesNoNo
OperatorYesYes, except credentials and webhooksNo
CustomWhat you chooseWhat you chooseOnly if you grant them

A tool only appears in the client if the role covers its permission. With the Analyst role you will see at most the 27 read tools, never the write ones.

How to manage or cut the connection

Each connection appears under Developers › API & MCP › Credentials as a credential of type MCP, named after the client that created it.

  • Deactivate: cuts access at once and can be switched back on.
  • Revoke: permanent. It also revokes its access and refresh tokens; to use the client again you have to connect anew.
  • Check from time to time which connections you have and remove the ones you no longer use.

With a token instead of OAuth

A bmc_live_… token from Credentials also works as an Authorization: Bearer header, with the same tool filtering: the client only sees the tools its permissions cover. It is the route for clients without OAuth, for your own agents and for working across several companies or groups at once.

  • Leave the token's Allowed IPs empty: the MCP server calls the API from BMC's infrastructure and a token with an IP list is rejected.
  • OAuth connections have no IP list.

Examples for each client in Connect your AI.

Troubleshooting

SymptomLikely causeWhat to do
The connection is established but the client shows 0 tools. The role or the account does not give permissions that open any tool. Check the role under Credentials. If it is Custom, add permissions; if the account has no data in those areas, there will be no tools.
OAuth error when authorising, or the account is not in the list. API access is not enabled on the account, or you are not an owner or administrator. Ask BMC to enable access (plataforma@bm.consulting) or ask an account administrator to do it.
The client asks you to authorise again after a while. The refresh token (30 days) or the expiry you set on the connection has run out. Connect again and, for fewer interruptions, choose a longer expiry.
The client rejects the registration or the redirect. It does not meet PKCE S256, registration as a public client or the redirect URI rules. Check the requirements under «Other MCP clients».

If the problem persists, write to plataforma@bm.consulting with the name of the MCP client and the time of the attempt.

Email
Contact