> ## 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.

# Using the MCP Server in Visual Studio Code

> Connect your Omni data to Visual Studio Code with Omni's MCP Server.

Visual Studio Code (VS Code) is a code editor that, when paired with GitHub Copilot, empowers development with AI-backed features. VS Code can connect with other tools—like Omni!—using MCP. Once successfully connected, you can interact with your Omni data right in VS Code's interface.

## 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:

* The latest version of [VS Code](https://code.visualstudio.com/) installed
* Access to [Copilot](https://code.visualstudio.com/docs/copilot/setup), which VS Code uses to run its [AI in Agent mode](https://code.visualstudio.com/docs/copilot/chat/mcp-servers)
* 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="Add the MCP Server">
        1. Open the **Command Palette** (`⌘ + Shift + P` on Mac, `Ctrl + Shift + P` on Windows).
        2. Search for `MCP` and select **MCP: Add Server**.
        3. Select **HTTP (HTTP or Server-Sent events)** and press **Enter**.
        4. Paste the OAuth URL and press **Enter**:
           ```txt theme={null}
           https://callbacks.omniapp.co/callback/mcp
           ```
        5. Enter a name for the server (e.g., `Omni MCP`) and press **Enter**.
        6. Select **Global** or **Workspace settings** and press **Enter**.
      </Step>

      <Step title="Start the MCP Server">
        VS Code should open a file named `mcp.json` and automatically prompt you to authorize the connection:

        <img src="https://mintcdn.com/omni-e7402367/XIpn-9Hi2cNutp5u/ai/images/vscode-auto-start-server.png?fit=max&auto=format&n=XIpn-9Hi2cNutp5u&q=85&s=2a6f973e3c7815c634f35e06ee5106cf" alt="" width="1723" height="1082" data-path="ai/images/vscode-auto-start-server.png" />

        If this doesn't happen, complete the following:

        1. Open the **Command Palette** again.

        2. Search for `MCP` and select **MCP: List Servers**.

        3. Click the **Omni** server in the list.

        4. Click **Start Server** or **Restart** above the server in the `mcp.json` file:

                   <img src="https://mintcdn.com/omni-e7402367/XIpn-9Hi2cNutp5u/ai/images/vscode-start-server.png?fit=max&auto=format&n=XIpn-9Hi2cNutp5u&q=85&s=e786d541e5557176f616b1df78432b12" alt="" width="629" height="259" data-path="ai/images/vscode-start-server.png" />

        5. When prompted, allow VS Code to open the browser.
      </Step>

      <Step title="Authorize the connection">
        1. Your browser will open and redirect you to an Omni authorization page.
        2. 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">
        You should see logs in the **Terminal** panel indicating the server started:

        ```shell theme={null}
        [info] Starting server Omni
        [info] Connection state: Starting
        [info] Starting server from LocalProcess extension host
        [info] Connection state: Running
        [info] Discovered 3 tools
        ```
      </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="Add the MCP Server">
        1. Open the **Command Palette** (`⌘ + Shift + P` on Mac, `Ctrl + Shift + P` on Windows).
        2. Search for `MCP` and select **MCP: Add Server**.
        3. Select **HTTP (HTTP or Server-Sent events)** and press **Enter**.
        4. Paste your Omni instance URL with `/mcp/https` appended:
           ```txt theme={null}
           https://<YOUR_OMNI_INSTANCE>/mcp/https
           ```
        5. Enter a name for the server (e.g., `Omni MCP`) and press **Enter**.
        6. Select **Workspace Settings** and press **Enter**.
      </Step>

      <Step title="Configure the MCP Server">
        A `.vscode/mcp.json` file was created in your project. Open it and update it to include headers:

        ```json title=".vscode/mcp.json" theme={null}
        {
          "inputs": {
            "type": "promptString",
            "id": "omni-mcp-key",
            "description": "API key for Omni Data MCP",
            "password": true
          },
          "servers": {
            "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)
        * `<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="Start the MCP Server">
        1. Open the **Command Palette** again
        2. Search for `MCP` and select **MCP: List Servers**
        3. Click the **Omni** server in the list
        4. Click **Start Server**

        You should see logs in the **Terminal** panel indicating the server started:

        ```shell theme={null}
        [info] Starting server Omni
        [info] Connection state: Starting
        [info] Starting server from LocalProcess extension host
        [info] Connection state: Running
        [info] Discovered 2 tools
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Using the MCP

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

<Steps>
  <Step>
    Open the chat panel (`⌃ + ⌘ + I` on Mac, `Ctrl + Alt + I` on Windows).
  </Step>

  <Step>
    Select [**Agent** mode](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_use-mcp-tools-in-agent-mode).
  </Step>

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

  <Step>
    By default, you need to confirm each tool invocation. Click **Continue** to proceed.
  </Step>

  <Step>
    The MCP Server will pick a model (if not configured for API key authentication) and topic, then run a query to retrieve the data.
  </Step>
</Steps>