> For the complete documentation index, see [llms.txt](https://docs.ox.security/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ox.security/api-documentation/api-reference/model-context-protocol/mcp-integration-using-oauth.md).

# MCP Integration Using OAuth

This guide explains how to connect your IDE or AI coding tool to OX Security by using the OX MCP server and your OX Security account.

The first time your tool connects, sign in to your OX Security account in your browser instead of creating an MCP Integration Key.

You can use this guide to configure:

* [Cursor with OX MCP](#integrating-cursor-with-ox-mcp)
* [Claude Desktop with OX MCP](#integrating-claude-desktop-with-ox-mcp)
* [Claude Code with OX MCP](#integrating-claude-code-with-ox-mcp)
* [Visual Studio Code with OX MCP](#integrating-visual-studio-code-with-ox-mcp)

The OX MCP server URL is: <https://mcp.app.ox.security/>

> **Note:** Browser sign-in is available only with the SaaS OX MCP server. If you use an on-premises deployment, authenticate by using an MCP Integration Key instead. For instructions, see [**MCP Integration Guide using an MCP Integration Key**](/api-documentation/api-reference/model-context-protocol/mcp-integration-guide.md).

## Log into OX Security

The following login process is applicable to any tool used with this integration method.

1. Log in to OX if you are not already signed in.

> **Note:** If your organization requires SSO, sign in using your enterprise email address.

2. Select the OX organization to authorize MCP access for.

> **Note:** If you belong to a single OX organization only, it is selected automatically, and this step is skipped.

<figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-32163a567b6ad9688ee75e6ad46c254b435a8db0%2F4_Select%20your%20org.png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

The **Authorization Complete** message appears, and you are redirected back to your IDE or AI coding tool; OX Security now appears as a connected MCP server.

<figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-7fde1b4b83711a8ba39b3f01e61eaf3ff82c706b%2F5_%20Authorization%20complete.png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

## Supported MCP clients and gateways

To protect the OAuth sign-in flow, OX accepts browser sign-in only from MCP clients and gateways with recognized OAuth callback URLs. This prevents authorization codes from being redirected to unauthorized sites.

The following clients and gateways are supported without additional configuration:

* Claude Desktop, Claude Code, and Claude on the web
* Visual Studio Code, including VS Code Insiders
* Cursor for web and desktop
* ChatGPT custom connectors
* Perplexity standard and enterprise custom connectors
* Cequence AI Gateway
* Locally running IDE, CLI, and agent clients that complete sign-in using a local callback address on your machine

If you use a different MCP client, gateway, or broker, contact OX Technical Support and provide the client name and OAuth callback URL. OX can enable the callback URL for your organization.

## Integrating Cursor with OX MCP

By integrating with OX's MCP, Cursor becomes a security-aware development assistant, able to query live security data, suggest actions, and triage issues directly from your IDE.

**To integrate Cursor with OX MCP:**

1. Click [here](cursor://anysphere.cursor-deeplink/mcp/install?name=ox-security\&config=eyJ1cmwiOiJodHRwczovL21jcC5hcHAub3guc2VjdXJpdHkvIn0%3D) to open Cursor in the relevant location where you can start working.
2. Select **Install**. No token or header configuration is required.

<figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-d41f966665aa50def7d021adec462665bf86f783%2Fmcp-oauth-cursor-1-install%20(1).png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

In the Cursor MCP settings, the **ox-security** server appears with a **Needs authentication** indication.

3. Select **Connect**.

<figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-390045deb79cc60498266f372f996e6b45debd52%2Fmcp-oauth-cursor-2-login%20(1).png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

The browser opens the OX Security authorization page.

4. Complete the login as described in [Logging in to OX Security](#logging-in-to-ox-security).

After logging in, the OX Security logo appears in the Cursor tools menu with the list of available tools. For more info, refer to [Cursor Documentation](https://docs.cursor.com/en/tools/developers).

<figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-75fc290c1b26090d4c20002f8b1a2a1189a76c0d%2Fmcp-oauth-cursor-3-tools%20(1).png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

## Integrating Claude Desktop with OX MCP

Claude Desktop connects to the OX MCP server as a custom connector, providing teams with robust security capabilities directly from their desktop environment. No local configuration file is required.

**To integrate Claude Desktop with OX MCP:**

1. In Claude Desktop, go to **Settings** > **Connectors**.
2. Select **Add custom connector**.
3. Set a name (for example, **OX Security**) and the URL:

```
https://mcp.app.ox.security/
```

4. Select **Add**.

<figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-84202ca55b4d9e1060af17bb5d473a392d0a305c%2Fmcp-oauth-claude-desktop-1-connector.png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

5. Open the new OX Security connector and select **Connect**.

The browser opens the OX Security authorization page.

6. Complete the login as described in [Log into OX Security](#log-into-ox-security).

<figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-d73d602f7d67d9855fca2c5cd47ca5b6d5306fa1%2Fmcp-oauth-claude-desktop-2-connect.png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

After authorization, OX Security tools are available in Claude Desktop conversations through the tools menu.

<figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-0816688510efb488d64bee8d60d852c00d2a8c6e%2Fmcp-oauth-claude-desktop-3-connected%20(3).png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

7. Review and adjust what Claude is allowed to do with each OX Security tool under **Settings** > **Connectors** > **OX Security** > **Tool permissions**.

<figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-5bb333ce0db883a84ef774dc6420e6052db74028%2Fmcp-oauth-claude-desktop-4-permissions.png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

### Integrating Claude Code with OX MCP

Claude Code, Anthropic's agentic coding tool for the terminal, connects to the OX MCP server directly from the command line, allowing developers to query live security data, triage issues, and get remediation guidance without leaving their coding session.

> **Note:** Ensure Claude Code is installed and up to date. To check your version, run `claude --version`; to update, run `claude update`.

**To integrate Claude Code with OX MCP:**

1. Open a terminal and run the following command:

```bash
claude mcp add --transport http ox-security https://mcp.app.ox.security/
```

2. Start Claude Code:

```bash
claude
```

3. Run the `/mcp` command, select **ox-security** (shown with a **needs authentication** status), and choose **Authenticate**.

<figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-b0fad21fff95f83f303fb37a5c2ade571631b6b7%2Fmcp-oauth-claude-code-1-needs-auth.png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

The browser opens the OX Security authorization page.

4. Complete the login as described in [Log into OX Security](#log-into-ox-security).

<figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-bad9a8280e7ca012ba96a9dbaeb44a37c5d976f8%2Fmcp-oauth-claude-code-2-auth.png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

5. Return to the terminal. The `/mcp` menu now shows **ox-security** with a **connected** status, along with the OX Security tools available to Claude Code.

<figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-6ce599dbf553d7d466afe9362ce59e289736e921%2Fmcp-oauth-claude-code-3-connected.png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

By default, the server is added only for the current project directory. To make it available in all of your projects, add `--scope user` to the command in step 1.

## Integrating Visual Studio Code with OX MCP

Visual Studio Code provides versatile options to connect with OX Security's MCP, enabling developers to streamline their security workflows within the VS Code ecosystem.

**To integrate VS Code with OX MCP:**

1. Open **VS Code Settings**.
2. Open **MCP User Configuration**, see [VS Code MCP Docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for details.

<figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-793f3324eacc0a2b73a9d5f39444b7667df39919%2Fmcp-oauth-vscode-1-config.png?alt=media" alt="" width="449"><figcaption></figcaption></figure>

3. Add the JSON MCP server configuration for OX Security in `mcp.json`:

```json
{
  "servers": {
    "ox-security": {
      "type": "http",
      "url": "https://mcp.app.ox.security/"
    }
  }
}
```

4. Save the configuration and start the server. When VS Code prompts that the MCP server requires authentication, select **Allow**.

The browser opens the OX Security authorization page. complete the login as described in [Log into OX Security](#log-into-ox-security).

<figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-1d9e82671b139966f8a42e8671603b435e6bdcea%2Fmcp-oauth-vscode-2-allow.png?alt=media" alt="" width="519"><figcaption></figcaption></figure>

5. In the **VS Code chat**, click **Add Context**.

<figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-1c19441f26949bf3bfe58825c4b6dcfc24e604fe%2Fmcp-oauth-vscode-3-addcontext.png?alt=media" alt="" width="444"><figcaption></figcaption></figure>

6. Select the desired tools.

<figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-ece98043cb07eae67b96e5f6197a6b85af10edea%2FVS3.png?alt=media" alt="" width="440"><figcaption></figcaption></figure>

OX Security appears as an available MCP server.

<figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-597cff03ffb16ad951a6263225e3d9773cffee04%2Fmcp-oauth-vscode-5-server.png?alt=media" alt="" width="382"><figcaption></figcaption></figure>

## Troubleshooting

Sign-in fails with "rejected the redirect URI" or `invalid_redirect_uri`

#### Symptoms

Your MCP client or gateway fails to register with the OX MCP server and displays an error similar to one of the following:

```
Dynamic Client Registration failed: The MCP server rejected the redirect URI (...)
```

```
{"error":"invalid_redirect_uri","error_description":"One or more redirect_uris are not permitted by this authorization server"}
```

#### Cause

The OAuth callback URL provided by the MCP client or gateway is not recognized by OX. OX allows authorization codes to be redirected only to approved callback URLs.

#### Resolution

To resolve the callback URL error:

1. Check whether your client is listed in the supported MCP clients and gateways.
2. If your client is not listed, contact OX Technical Support and provide:
   * The name and version of the MCP client, gateway, or broker.
   * The full OAuth callback URL shown in the error message.
   * Whether the callback URL is shared by all customers of the provider or is specific to your organization.
3. After OX reviews and approves the callback URL, retry the sign-in flow.

No additional configuration is required on your side after the callback URL is enabled.

If you cannot connect your MCP client or provider to OX MCP for another reason, contact OX Technical Support and provide the client name and the error message.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ox.security/api-documentation/api-reference/model-context-protocol/mcp-integration-using-oauth.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.