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

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.omni.co/feedback

```json
{
  "path": "/ai/mcp/cursor",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# Using the MCP Server in Cursor

> Connect your Omni data to Cursor with Omni's MCP Server.

Cursor is an AI-powered code editor that can connect with other tools—like Omni!—with MCP. Once successfully connected, you can interact with your Omni data right in Cursor's interface.

**Looking for the Omni agent skills for Cursor?** See the [Agent skills documentation](/developers/agent-skills) for a broader set of skills beyond querying.

## Requirements

<Note>
  Every person who wants to use the MCP Server must complete the setup.
</Note>

To follow the steps in this guide, you'll need:

* **A version of [Cursor](https://cursor.sh/) that supports MCP**
* **To have the following enabled in Omni**:
  * **The MCP Server AI setting**. An Organization Admin can enable this setting by navigating to **Settings > AI > General**.
  * **Personal access tokens (PATs)**, which are required to use [OAuth to authenticate](/ai/mcp/authentication). An Organization Admin can activate them by going to [**Settings > API Keys > Personal tokens**](/api/authentication#personal-access-tokens-pat).

## Setup

Choose your authentication method. See the [MCP authentication guide](/ai/mcp/authentication) if you need help selecting a method.

<Tabs>
  <Tab title="OAuth (Recommended)">
    OAuth provides streamlined setup without manually managing API keys.

    <Steps>
      <Step title="Open MCP settings">
        In Cursor, click **Cursor > Settings > Cursor settings**.
      </Step>

      <Step title="Add a new MCP server">
        Click **Tools & Integrations** in the settings navigation, then click **New MCP Server** under **MCP Tools**.
      </Step>

      <Step title="Configure the server">
        Cursor will create an `mcp.json` file. Paste the following:

        ```json title="mcp.json" theme={null}
        {
          "mcpServers": {
            "Omni": {
              "url": "https://callbacks.omniapp.co/callback/mcp"
            }
          }
        }
        ```

        Save the file.
      </Step>

      <Step title="Authorize the connection">
        Before you can use the MCP, you'll need to authorize the connection.

        1. Click the **Connect** button next to the MCP.
        2. Your browser will open and redirect you to an Omni authorization page.
        3. Review the requested permissions and click **Authorize**.

        Omni will automatically create a [Personal access token](/api/authentication#personal-access-tokens-pat) and link it to your Omni user account.
      </Step>

      <Step title="Verify the connection">
        At this point, you should be able to use the Omni MCP server in Cursor chats.

        <img src="https://mintcdn.com/omni-e7402367/XIpn-9Hi2cNutp5u/ai/images/cursor-connected-mcp.png?fit=max&auto=format&n=XIpn-9Hi2cNutp5u&q=85&s=4d8867279028ff8a85ed38094cf2c7ef" alt="Cursor MCP Server status" width="1382" height="641" data-path="ai/images/cursor-connected-mcp.png" />
      </Step>
    </Steps>
  </Tab>

  <Tab title="API Key">
    API key authentication gives you direct control over key management.

    <Steps>
      <Step title="Create an API key">
        If you don't have an Omni API key, [create one](/api/authentication) before continuing.
      </Step>

      <Step title="Open MCP settings">
        Open the **Command Palette** (`⌘ + Shift + P` on Mac, `Ctrl + Shift + P` on Windows), search for `MCP`, and select **View: Open MCP Settings**.
      </Step>

      <Step title="Add a new MCP server">
        Click **Tools & Integrations** in the settings navigation, then click **New MCP Server** under **MCP Tools**.
      </Step>

      <Step title="Configure the server">
        Cursor creates an `mcp.json` file. Paste the following:

        ```json title="mcp.json" theme={null}
        {
          "mcpServers": {
            "Omni": {
              "url": "https://<YOUR-OMNI-INSTANCE>/mcp/https",
              "headers": {
                "Authorization": "Bearer <OMNI_API_KEY>",
                "X-MCP-Model-ID": "<OPTIONAL_OMNI_MODEL_ID>",
                "X-MCP-Topic-Name": "<OPTIONAL_TOPIC_NAME>",
                "X-MCP-User-Required": "<true/false>",
                "X-MCP-User-ID": "<OPTIONAL_OMNI_USER_ID>",
                "X-MCP-Query-All-Views": "<true/false>"
              }
            }
          }
        }
        ```
      </Step>

      <Step title="Replace placeholder values">
        * `<YOUR_OMNI_INSTANCE>` - **Required**. Your Omni URL (e.g., `acme.omniapp.co`)
        * `<OMNI_API_KEY>` - **Required**. Your [Omni API key](/api/authentication). Cursor also supports [environment variables](https://docs.cursor.com/context/model-context-protocol#authentication) for the key.
        * `<OPTIONAL_OMNI_MODEL_ID>` - **Optional**. Scope the MCP to a specific model. Find the model ID in the URL when viewing the model:
          ```txt wrap theme={null}
          https://acme.omniapp.co/models/9d9440e5-8522-4507-b092-1ac26ba26673/ide/model
          ```
        * `<OPTIONAL_TOPIC_NAME>` - **Optional**. Scope the MCP to a specific topic
        * `<true/false>` - **Optional**. Require a User ID to execute queries with that user's permissions (default: false)
        * `<USER_ID>` - **Optional**. Execute queries as this user. Get IDs from the [List Users API](/api/users/list-users)
        * `<true/false>` for `X-MCP-Query-All-Views` - **Optional**. Set to `true` to allow the AI to query any view in the model instead of only topics. Requires the model's [`query_all_views_and_fields`](/modeling/models/ai-settings#param-query-all-views-and-fields) setting to be enabled. Defaults to `false`.

        Save the file.
      </Step>

      <Step title="Verify the connection">
        Check the server's status in **Settings**:

        <img src="https://mintcdn.com/omni-e7402367/t-IfvrVPwJe-flyV/ai/images/mcp-cursor-status.png?fit=max&auto=format&n=t-IfvrVPwJe-flyV&q=85&s=7aebb6e584d46c03d8118fb3d724be67" alt="Cursor MCP Server status" width="1193" height="572" data-path="ai/images/mcp-cursor-status.png" />
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Using the MCP

Once the MCP Server is connected, Cursor automatically uses it when you ask questions about your data. You can prompt Cursor to use Omni by referring to it by name or description.

<Steps>
  <Step>
    Open the AI pane/chat panel and select **Agent** mode:

    <img src="https://mintcdn.com/omni-e7402367/t-IfvrVPwJe-flyV/ai/images/cursor-chat-agent-mode.png?fit=max&auto=format&n=t-IfvrVPwJe-flyV&q=85&s=8af0854fddd3942da8e60c48aa20def8" alt="Cursor chat panel with Agent mode selected" width="656" height="331" data-path="ai/images/cursor-chat-agent-mode.png" />
  </Step>

  <Step>
    Enter a prompt, such as `Hey Omni, tell me how many users have been sourced by search and email`.
  </Step>

  <Step>
    Each time Cursor uses an MCP tool, you'll be prompted [to approve its usage](https://docs.cursor.com/context/model-context-protocol#tool-approval). Click **Run tool** to proceed.

    <img src="https://mintcdn.com/omni-e7402367/t-IfvrVPwJe-flyV/ai/images/cursor-mcp-approval.png?fit=max&auto=format&n=t-IfvrVPwJe-flyV&q=85&s=e8485d465fef5cd2eaa58285037463ad" alt="Cursor MCP tool approval prompt" width="512" height="209" data-path="ai/images/cursor-mcp-approval.png" />

    You can also use Cursor's [Yolo mode](https://docs.cursor.com/chat/agent#yolo-mode) to automatically run MCP tools without requiring approval.
  </Step>

  <Step>
    The MCP Server will pick a model (if not configured) and topic, then run a query to retrieve the data:

    <img src="https://mintcdn.com/omni-e7402367/t-IfvrVPwJe-flyV/ai/images/cursor-run-query.png?fit=max&auto=format&n=t-IfvrVPwJe-flyV&q=85&s=adb4a618d6b0e6a17167bafd516798de" alt="Cursor running an MCP query" width="512" height="450" data-path="ai/images/cursor-run-query.png" />
  </Step>
</Steps>