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.
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. ThePOST /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, calllist_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 ofcreate_* write tools, plus
update_group, update_plan, update_quota_values, update_exchange_rates, update_dashboard 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, a dashboard with no tiles. Configuring the resource further
(loading values, attaching metrics, pinning tiles) is done from the Qobra web
app, with a few exceptions: 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,
update_dashboard renames a dashboard, create_record adds one record to a
data table with its values filled in, update_record changes or archives an
existing record, and split_record splits a record between users.
Connect an MCP client to Qobra
Prerequisites, the OAuth consent flow, and how to add the server to Claude,
ChatGPT or Dust.