> ## Documentation Index
> Fetch the complete documentation index at: https://docs.captivateiq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP

> Connect Claude and other AI tools to your CaptivateIQ compensation and planning data with the CaptivateIQ MCP server.

<Warning>
  The CaptivateIQ MCP server is in early access. Tools, setup steps, and behavior may change.
</Warning>

Connect your AI tools to your CaptivateIQ data with MCP (Model Context Protocol). Once connected, you can look up commission plans and employees, review payouts and payout dates, explore workbooks and reports, and export worksheets, all from your AI assistant.

<Note>
  MCP access must be enabled for your organization. Organizations without access receive a 403 error when signing in. To request early access, contact [support@captivateiq.com](mailto:support@captivateiq.com).
</Note>

<Info>
  Using Claude? Add CaptivateIQ from the [Claude directory](/connectors/claude) for the simplest setup. The instructions below cover custom MCP connections for Claude and other AI tools.
</Info>

## Pre-requisites

* A CaptivateIQ account in an organization with MCP access enabled. During early access, MCP is intended for organization admins, and what you can see depends on your role
* An AI tool that supports MCP over Streamable HTTP with OAuth, such as Claude

## How to connect

### Claude

For the simplest setup, follow the [Claude directory guide](/connectors/claude). To connect manually with a custom connector, use the steps below.

<Note>
  Custom connectors require a Claude plan that supports them.
</Note>

1. Open [Claude](https://claude.ai) and sign in

2. Go to [**Customize → Connectors**](https://claude.ai/customize/connectors)

3. Click **+** then **Add custom connector**

4. Enter the CaptivateIQ MCP server URL:

   ```text theme={null}
   https://mcp.app.captivateiq.com/mcp
   ```

5. Click **Add**, then complete the OAuth sign-in with your CaptivateIQ account

6. In a new chat, click **+ → Connectors** and toggle CaptivateIQ on

7. Ask "Who am I in CaptivateIQ?" Claude should call `ciq_get_current_user` and return your name and organization

<Tip>
  On Team and Enterprise plans, an Owner may first need to add the connector in [**Organization settings → Connectors**](https://claude.ai/admin-settings/connectors). Members can then connect to it from **Customize → Connectors**.
</Tip>

### Claude Code

Claude Code connects with a pre-registered client ID, because the CaptivateIQ MCP server does not support dynamic client registration.

1. Contact [support@captivateiq.com](mailto:support@captivateiq.com) to request a client ID for Claude Code

2. Add the CaptivateIQ MCP server in your terminal, replacing `<client-id>` with the ID you received:

   ```bash theme={null}
   claude mcp add captivateiq --transport http https://mcp.app.captivateiq.com/mcp --client-id <client-id>
   ```

3. Start Claude Code in the same terminal:

   ```bash theme={null}
   claude
   ```

4. Run `/mcp`, select the CaptivateIQ MCP server, and select **Authenticate**

5. Sign in with your CaptivateIQ account in the browser window that opens

6. Ask "Who am I in CaptivateIQ?" Claude Code should call `ciq_get_current_user` and return your name and organization

### Other AI tools

You can connect any MCP-compatible tool using the production URL:

```text theme={null}
https://mcp.app.captivateiq.com/mcp
```

Your AI tool must support:

* [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)
* **OAuth 2.0 authentication with PKCE.** CaptivateIQ uses browser-based OAuth, so your tool needs to open a browser window for you to sign in with your normal CaptivateIQ login. No API tokens are needed.
* **A pre-registered client ID.** The server does not support dynamic client registration. Contact [support@captivateiq.com](mailto:support@captivateiq.com) to request a client ID.

The configuration format differs by client, so check your client's MCP documentation. If your client cannot complete sign-in, contact [support@captivateiq.com](mailto:support@captivateiq.com) with the name of the client.

## Available tools

Once connected, these tools are available to your AI assistant. Refresh the tools list in your client to pick up new tools.

| Tool | Description | Example prompts |
| - | - | - |
| `ciq_get_current_user` | Identify who you are signed in as: your name, email, role, and organization | *Who am I in CaptivateIQ?* |
| `ciq_get_current_organization` | Identify the organization you are connected to and whether it is a live or sandbox environment | *Which CaptivateIQ organization am I connected to?* |
| `ciq_get_organization_summary` | Count the employees, commission plans, data workbooks, and transformation workbooks you can see | *How big is our CaptivateIQ organization?* |
| `ciq_retrieve_plans` | List commission plans, or get one in full, with its period groups and payout dates. Filter by name | *Which commission plans are active?* |
| `ciq_retrieve_employees` | List employees, or find one by name or employee ID. Plan enrollments are not included | *Find the employee named Alex Smith* |
| `ciq_retrieve_employee_assignments` | See which employees are assigned to which plans and period groups, with date ranges | *Which plans is employee 1042 enrolled in?* |
| `ciq_retrieve_employee_assumptions` | Get employee assumptions for a period group, including custom values such as quota, territory, or rate | *What is Alex's quota in the Q3 period group?* |
| `ciq_retrieve_period_groups` | List or search period groups, optionally for one plan, with their payout dates and workbooks | *Show the period groups for the Sales Commission plan* |
| `ciq_retrieve_worksheets` | List the worksheets in a workbook, or get one worksheet. Filter by name or type | *What worksheets are in the Q3 Commissions workbook?* |
| `ciq_retrieve_columns` | List a worksheet's columns, or get one column with its description, formula, and data type | *What columns does the Commission worksheet have, and how is Attainment calculated?* |
| `ciq_retrieve_payouts` | Retrieve published payouts, or unpublished ones on request, by employee, plan, or payout date, with amounts and currency | *Show published payouts for the latest payout date* |
| `ciq_retrieve_payout_dates` | List payout dates, for a plan or a period group | *When are the next payout dates for the Sales plan?* |
| `ciq_retrieve_data_workbooks` | List data workbooks. Filter by name or active status | *What data workbooks do we have?* |
| `ciq_retrieve_transformation_workbooks` | List transformation workbooks. Filter by name or active status | *List our active transformation workbooks* |
| `ciq_retrieve_report_models` | List Report Models, which are point-in-time snapshots of calculation results rather than live data | *Which report models do we have?* |
| `ciq_retrieve_report_outputs` | List the outputs of a Report Model, optionally for a period date range or only locked outputs | *Show the locked outputs of the Commission report model this year* |
| `ciq_export_worksheet` | Start an export of a worksheet to a CSV file | *Export the Closed Deals data worksheet* |
| `ciq_export_report_output` | Start a CSV export of a Report Output's snapshot data | *Export the June output of the Commission report model* |
| `ciq_get_export_status` | Check the status of an export. When it finishes, returns the first 100 rows inline and a download link for the full file | *Is my export finished?* |
| `ciq_search_knowledge_base` | Search the CaptivateIQ product documentation, or read one documentation page in full. Requires Knowledge Center access and knowledge base search enabled for your organization | *How do I configure payouts for a commission plan?* |

## Permissions and data access

* Requests run as the signed-in user. There are no shared service accounts.
* Role-based permissions in CaptivateIQ apply to every tool.
* Access tokens are short-lived and refreshed automatically.

## Troubleshooting

### 403 after signing in

MCP access is not enabled for your organization, or your user lacks permission. To request early access, contact [support@captivateiq.com](mailto:support@captivateiq.com). If access is enabled, contact your CaptivateIQ admin about your permissions.

### Tools missing or outdated

If CaptivateIQ is connected but tools are missing, outdated, or Claude shows **No tools available**:

1. Go to [Customize → Connectors](https://claude.ai/customize/connectors) (must be on claude.ai, even if you use the desktop app)
2. Find the CaptivateIQ connector
3. Click the three-dot menu and choose **Refresh tools list**

### Client cannot register or sign in

Your client may not be supported yet. See [Other AI tools](#other-ai-tools).

## FAQ

<AccordionGroup>
  <Accordion title="Do I need a client ID when connecting other tools?">
    Yes. The CaptivateIQ MCP server does not support dynamic client registration, so other AI tools need a pre-registered client ID. Contact [support@captivateiq.com](mailto:support@captivateiq.com) to request one. Claude does not need one. See [Claude Code](#claude-code) and [Other AI tools](#other-ai-tools).
  </Accordion>

  <Accordion title="Can I connect CaptivateIQ MCP to my own internal AI tool?">
    Possibly. Any tool implementing the [MCP client specification](https://modelcontextprotocol.io/) with Streamable HTTP transport and OAuth 2.0 can connect, subject to the client registration requirements above. Contact [support@captivateiq.com](mailto:support@captivateiq.com) if you need help.
  </Accordion>

  <Accordion title="Can the MCP server change my compensation data?">
    No tool modifies or deletes compensation data. The two export tools start a CSV export and create a file for download.
  </Accordion>
</AccordionGroup>