Qobra MCP server

The Qobra MCP server exposes a set of tools over the Model Context Protocol, so an MCP client like Claude, ChatGPT, Gemini or Dust can answer questions about your Qobra workspace and make changes to it 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, Gemini 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.

​

Argument conventions

• Unknown arguments are ignored. The server drops any argument a tool does not declare, without an error. A misspelled or renamed filter, such as created_after instead of after, silently stops filtering. Use the exact names listed on each tool page.
• Date bounds are after and before. Tools that filter by date, such as list_imports and list_sales_coach_discussions, take inclusive after and before bounds. Each accepts an absolute ISO-8601 date/time (2026-07-01) or a duration relative to now (-P7D for the last 7 days).
• Periods are year-first. A period is written YYYY (a year), YYYY-SX (a semester), YYYY-QX (a quarter) or YYYY-MM (a month).
• A user is designated by user_id. Pass the user’s id or exact email, never a name. Every other resource is designated by its id, taken from the tool that lists or returns it. search arguments are for finding a resource, not for designating one.
• An id outside your access reads like an unknown id. Qobra answers the same way for both, so find the resource again from the tool that lists it rather than retrying.
• Omit an optional argument instead of sending null. Where an argument says "" clears it, an empty string empties the value. Null never clears anything.
• Lists page with limit and offset. Most paginated tools take a limit from 1 to 250, defaulting to 50. A few cap it lower, and each tool page states its range. The server refuses a value outside that range. Omit offset for the first page, then pass the returned next_offset to read the next one. A null next_offset means you are on the last page. Tools without limit return everything at once.

​

Available tools

Read tools are always exposed, scoped to the authenticated user’s company and role-based permissions. Write tools are also available to every company with the MCP enabled. See Write tools 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. recalculate_statements also accepts sandbox_id, to recalculate a sandbox’s statements instead of the live ones.

​

Write tools

The MCP server also exposes a family of create_* and update_* write tools, plus archive_quota, split_record, answer_request, recalculate_statements, approve_statements and trigger_import, so an MCP client can change your Qobra workspace from a conversation. The write tools are available to every company with the MCP enabled. 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. Qobra hides a write tool the caller’s role refuses at discovery, so the MCP client never plans a write it cannot make. A write over a resource behind its own feature, such as requests or the validation workflow, also needs that feature switched on for the company, as in the web app. ask_architect and get_architect_turn are the exception: they are reserved to demonstration companies, and also need the Architect switched on for the company. Elsewhere, Qobra hides them at discovery. 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). trigger_import writes no audit event: the import it launches shows up in list_imports instead. 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 unless it is given a default. Configuring the resource further (loading values, attaching metrics) is done from the Qobra web app, with a few exceptions: create_plan and create_group can attribute their members in the same call, 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, update_request changes, closes or reopens a request, update_user_managers declares who a user reports to, and update_user_attribute_values sets a user’s attribute values. The settings of an existing resource are changed with its update_* tool (update_data_table, update_data_table_field, update_group_dimension, update_quota, update_user_attribute, update_user), and archive_quota archives or restores a quota. trigger_import launches the import of a data table, a quota or an integration from the system it syncs from. Removing a tile from a dashboard is still done from the Qobra web app. On statements, update_statements_status locks, unlocks, pays or unpays statements and can request their validation, approve_statements approves the validation stages awaiting you, update_statement_adjustments overrides computed values, and update_statement_payments writes manual payments, the draw and the carried balance. The write tools that change data a statement reads from (records, quota values, exchange rates) do not recalculate statements: call recalculate_statements afterwards on the users and periods the change touches. To build or change a compensation’s calculation from a conversation, use ask_architect. It hands the work to Qobra’s Architect agent, one turn per call, and saves the changes as the compensation’s draft. Publishing the draft is done from the Qobra web app. ask_architect is reserved to demonstration companies, and the Architect must also be switched on for the company.