Skip to main content
The Qobra MCP server is enabled per company. A Qobra admin turns on AI and the MCP agent in Settings > AI. If the MCP agent is in pilot mode, only users in the pilot group can connect. Every tool is scoped to your Qobra user’s permissions.
The Qobra MCP server exposes a set of tools over the Model Context Protocol, so an MCP client like Claude, ChatGPT or Dust can answer questions about your Qobra workspace and help build a demo end to end straight from a conversation. It covers data tables, integrations, users, roles, groups, quotas, compensation plans, commission letters, reports, requests, statements, imports, audit logs, Sales Coach discussions, Help Center articles and sandboxes, plus an impact analysis of everything that depends on a resource.

​
What these pages document

Each tool page describes a tool’s inputs and the shape of what it returns. These are MCP tools, not REST endpoints: you never call them over HTTP yourself — you connect an MCP client (Claude, ChatGPT or Dust) to the server, and the model calls the tools for you. The POST /mcp/tools/<name> shown on each page is only how we render a tool’s request and response schema.

​
Available tools

Read tools are always exposed, scoped to the authenticated user’s company and role-based permissions. Write tools are gated separately — see Write tools (beta) below.

​
Reading a sandbox

Every tool reads your company’s live environment (its real compensation data) by default. If your company uses sandboxes and your role can read them, call list_sandboxes to discover them, then pass a sandbox’s id as the sandbox_id argument of a list tool (list_plans, list_quotas, list_statements, list_statement_periods, list_reports, list_dashboards) to read that sandbox instead. sandbox_id only accepts a sandbox’s id — never a sandbox name, and never the live environment’s own id (omit the argument to read the live environment). Tools that take a resource id — such as get_plan, get_statement or get_report — need no sandbox_id argument: the id itself names the environment the resource lives in. The write tools that create an environment-scoped resource (create_quota, create_plan, create_report, create_dashboard) accept the same sandbox_id argument to say which environment the new resource lands in. Omit it to write to the live environment. create_compensation does not: which environment it lands in is decided by the plan it hangs off.

​
Write tools (beta)

The MCP server also exposes a family of create_* write tools, plus update_group, update_plan, update_quota_values, update_exchange_rates, update_dashboard, update_request and answer_request, so an MCP client can build a demo end to end from a conversation. This surface is in beta and enabled per company — where it is not enabled, the write tools are hidden at discovery, and Qobra refuses any attempt to call one with a message that says the beta is not enabled for the company. Read tools are unaffected. Every write tool is scoped to the caller’s role-based permissions in the same way a read tool is — a user without write access on plans cannot call create_plan, exactly as they cannot create a plan from the web app. Every write is recorded in the audit trail, as the Qobra MCP agent, so a change made by a model shows up in the trail alongside changes made from the web app and by other integrations. The MCP audits writes to the live environment only, mirroring the audit trail’s own behavior — a write into a sandbox is not audited (the trail scopes to live). The write surface today: Each create_* tool creates an empty resource — a plan with no compensation, a quota with no target values, a data table field with no values on any record. Configuring the resource further (loading values, attaching metrics) is done from the Qobra web app, with a few exceptions: create_dashboard can add reports to the new dashboard and arrange its tiles in the same call, update_dashboard renames a dashboard, adds reports to it and arranges its tiles, update_plan declares a plan’s membership in one call, update_quota_values sets a quota’s target values, update_exchange_rates sets the rates of one exchange-rate range, create_record adds one record to a data table with its values filled in, update_record changes or archives an existing record, split_record splits a record between users, create_request opens a request with its statements, members and assignee, and update_request changes, closes or reopens a request. Removing a tile from a dashboard is still done from the Qobra web app.

Connect an MCP client to Qobra

Prerequisites, the OAuth consent flow, and how to add the server to Claude, ChatGPT or Dust.