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

# MCP authentication

> Choose how to authenticate MCP clients with your Omni instance: OAuth for streamlined setup or API keys for manual control.

The Omni MCP Server supports two authentication methods. Choose the one that best fits your needs:

|                  | OAuth                                         | API key                                                |
| ---------------- | --------------------------------------------- | ------------------------------------------------------ |
| Best for         | Individual users who want quick, secure setup | Admins managing keys centrally, or automated workflows |
| Setup complexity | Low - browser flow                            | Medium - manual configuration                          |
| Key management   | Automatic                                     | Manual                                                 |
| User permissions | Uses your permissions                         | Uses key creator's permissions                         |

## OAuth authentication

OAuth lets MCP clients connect to Omni without requiring you to manually create and manage API keys. When you connect, Omni creates an API key on your behalf and links it to your user account.

<Note>
  PATs generated through MCP OAuth are different from standard PATs. See the [MCP OAuth PATs section](#mcp-oauth-pats) for more information.
</Note>

### Requirements

To use OAuth authentication with the MCP Server, your organization must have:

* **The MCP server AI setting** enabled - Organization Admins can enable this setting in **Settings > AI > General**
* **Personal access tokens (PATs)** enabled - Organization Admins can activate them by going to **Settings > API Keys > Personal tokens**

### How it works

<Note>
  The OAuth flow will use the cookie of the last Omni instance you logged into when redirecting you to the authorization page. If you are a member of multiple organizations, log out and then log back in to the organization you want to connect to immediately before starting the OAuth flow.
</Note>

When you first connect an MCP client to Omni using OAuth, the flow will look similar to the following:

1. You add the [connection URL](#connection-url) to your MCP client.
2. The MCP client will trigger the OAuth flow.
3. Your browser will open to an authorization page for your Omni organization.
4. Review the permissions on the authorization page.
5. Click **Authorize**.
6. Omni will automatically create an [**MCP OAuth PAT**](#mcp-oauth-pats) for the MCP client and link it to your Omni user account.

After authorization, all MCP queries use your Omni permissions and access controls. The flow uses OAuth 2.1 with PKCE for security.

### MCP OAuth PATs

When you authenticate via OAuth, Omni automatically creates a special PAT called an **MCP OAuth PAT**. These differ from standard PATs in a few ways:

<Steps>
  <Step title="Any user can create one">
    Standard PATs require **Restricted Querier** or higher permissions, but MCP OAuth PATs are created automatically for any user who completes the OAuth flow. This can include **Viewers**.
  </Step>

  <Step title="Permissions reflect the user's in-app permissions">
    MCP OAuth PATs inherit the creating user's in-app permissions.

    This means that while **Viewers** can create an MCP OAuth PAT, they won't be able to run queries or retrieve data through MCP since their permissions don't allow querying in-app.
  </Step>

  <Step title="Not visible in Omni">
    MCP OAuth PATs are not currently visible in Omni.

    <Tip>
      While these PATs can't currently be viewed in the Omni app, you can use the [List API tokens endpoint](/api/api-tokens/list-api-tokens) to retrieve information about MCP-generated PATs.
    </Tip>
  </Step>
</Steps>

Organization Admins can disable and re-enable MCP OAuth PATs in **Settings > API access > Personal tokens** or by using the [Enable or disable API token endpoint](/api/api-tokens/enable-or-disable-api-token).

For a full comparison of all API key types in Omni, refer to the [API authentication](/api/authentication) documentation.

### Connection URL

Use this URL when setting up OAuth in your MCP client:

```text theme={null}
https://callbacks.omniapp.co/callback/mcp
```

This URL routes requests to your Omni organization after you identify yourself during the OAuth flow.

## API key authentication

API key authentication gives you direct control over key creation and management. This approach is useful when:

* You need to manage API keys centrally for your organization
* You're setting up automated workflows or CI/CD pipelines
* You want to use a service account rather than individual user credentials
* Your MCP client doesn't support OAuth

### How it works

1. Create an [API key in Omni](/api/authentication)
2. Configure the key in your MCP client's settings
3. The client includes the key in all requests to Omni

### Connection URL

When using API key authentication, connect directly to your Omni instance:

```text theme={null}
https://<YOUR_OMNI_INSTANCE>/mcp/https
```

Replace `<YOUR_OMNI_INSTANCE>` with your Omni URL (e.g., `acme.omniapp.co`).

## Troubleshooting

### OAuth issues

<AccordionGroup>
  <Accordion title="&#x22;Personal Access Tokens aren't enabled&#x22; (403 error)">
    Ask an admin to enable PATs: **Settings > API Keys > Personal tokens**
  </Accordion>

  <Accordion title="MCP server access disabled (403 error)">
    Your organization has disabled MCP server access. Ask an admin to enable it: **Settings > AI > General > MCP server**
  </Accordion>

  <Accordion title="Authorization flow doesn't start">
    * Verify your MCP client supports OAuth 2.1 with PKCE
    * Check that you're using the correct URL: `https://callbacks.omniapp.co/callback/mcp`
    * Ensure your Omni instance is accessible from your browser
  </Accordion>

  <Accordion title="Authorization fails after clicking &#x22;Authorize&#x22;">
    * Check that your browser allows redirects to the MCP client
    * Verify you have permission to create API keys in your organization
    * Try disconnecting and reconnecting the MCP client
  </Accordion>
</AccordionGroup>

### API key issues

<AccordionGroup>
  <Accordion title="Authentication fails">
    * Verify the API key is correct and hasn't been revoked
    * Check that the key has appropriate permissions
    * Ensure you're using the correct instance URL
  </Accordion>
</AccordionGroup>

### General issues

<AccordionGroup>
  <Accordion title="Queries fail after successful authorization">
    * Confirm the API key is active in your Omni settings
    * Verify you have access to the model and topics you're querying
    * Check that your Omni user permissions allow data access
  </Accordion>
</AccordionGroup>

## Next steps

Ready to connect? Follow the setup guide for your MCP client:

<Columns cols={3}>
  <Card title="ChatGPT" href="/ai/mcp/chatgpt" icon="message-bot">
    OpenAI's AI assistant with developer mode
  </Card>

  <Card title="Claude Code" href="/ai/mcp/claude-code" icon="code">
    Command-line based version of Anthropic Claude
  </Card>

  <Card title="Claude Desktop" href="/ai/mcp/claude-desktop" icon="desktop">
    App version of Anthropic Claude
  </Card>

  <Card title="Codex" href="/ai/mcp/codex" icon="terminal">
    OpenAI's agentic coding tool
  </Card>

  <Card title="Cursor" href="/ai/mcp/cursor" icon="arrow-pointer">
    AI-powered IDE designed for fast, agentic programming
  </Card>

  <Card title="Visual Studio Code" href="/ai/mcp/vscode" icon="microsoft">
    Popular open-source IDE with powerful AI features
  </Card>
</Columns>