> For the complete documentation index, see [llms.txt](https://docs.apono.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.apono.io/docs/agent-privilege-guard/set-up-apono-agent-privilege-guard/apono-agent-privilege-guard-for-custom-oauth-mcps.md).

# Apono Agent Privilege Guard for Custom OAuth MCPs

Configure governed, just-in-time AI access to OAuth-protected custom MCP servers

Set up Apono Agent Privilege Guard for Custom OAuth MCPs to give AI agents controlled, temporary access to an MCP server your organization runs or any OAuth MCP server that is not available as an Apono Managed MCP.

An Apono admin creates a Custom MCP (OAuth) integration for the server, adds the MCP server to Apono, and creates an agentic access flow. Each user then connects a supported AI client through the Local Agentic Gateway, which brokers requests between the AI client, Apono, and the MCP server.

{% hint style="danger" %}
Each OAuth MCP server requires its own **Custom MCP (OAuth)** integration, custom MCP configuration, and agentic access flow. Access is requested and granted per server, and each server appears as its own target to the agent.
{% endhint %}

***

### Set up the Apono account

An Apono admin completes this setup once for each OAuth MCP server that agents need to access.

After the Apono account setup is complete, each user can connect a supported AI client to the Agentic Gateway.

#### Prerequisites

<table><thead><tr><th width="200.3828125">Requirement</th><th>Details</th></tr></thead><tbody><tr><td><strong>OAuth MCP integration</strong></td><td><p>Connected Apono integration for this OAuth MCP server</p><p><br>Verify that the integration exists and is healthy on the <a href="https://app.apono.io/catalog/connected"><strong>Connected</strong></a> tab. If no custom OAuth MCP integration is connected, follow the <a href="/docs/additional-integrations/mcps/custom-mcp-oauth.md">Custom MCP (OAuth) integration docs</a>.</p></td></tr><tr><td><strong>OAuth authorization</strong></td><td><p>Authorization server that supports either Dynamic Client Registration (DCR) or a pre-registered public client with PKCE</p><p><strong>Additional information</strong>:</p><ul><li>OAuth client ID for a pre-registered client</li><li>Accepted scopes, if required by the server</li><li>Device authorization endpoint, if required by the server</li></ul><p><strong>IMPORTANT</strong>: Client-secret authentication and other OAuth methods are <strong>not supported</strong>.</p></td></tr></tbody></table>

#### Create an agentic access flow

Create a Self Serve access flow that allows agents to request temporary access to the custom OAuth MCP on behalf of permitted users:

1. Follow the procedure in [Self Serve Access Flows](/docs/access-flows/creating-access-flows-in-apono/self-serve-access-flows.md) to define the requestors, resources, access duration, and approval process. As you create the flow, apply the following settings for agentic access.

<table><thead><tr><th width="199.6015625">Setting</th><th>Configuration</th></tr></thead><tbody><tr><td><strong>Access Flow Name</strong></td><td>Enter a unique, user-friendly name, such as <em>Agentic - Custom OAuth MCP</em>.</td></tr><tr><td><strong>When Requestor</strong></td><td>Select the users or groups on whose behalf an agent can request access.<br><br>The agent can request access only on behalf of its associated user, so that user must match these requester conditions. For <strong>Can request for</strong>, select <strong>Themselves</strong>.</td></tr><tr><td><strong>Request access to</strong></td><td><p>Select the Custom MCP (OAuth) integration for the server, and then select the <strong>User</strong> resource type and the <strong>Impersonate</strong> permission.</p><p><br>Follow the <strong>Integrations</strong> instructions in the <strong>Define the resource</strong> section of the <strong>Self Serve Access Flows</strong> guide.</p></td></tr><tr><td><strong>Grant for</strong></td><td>Set the access duration to <strong>5 minutes</strong>.</td></tr><tr><td><strong>Approval</strong></td><td>Select <strong>Automatic</strong></td></tr><tr><td><strong>Settings</strong></td><td>Click the <strong>Restrict to agentic access</strong> toggle to enable the setting.</td></tr></tbody></table>

{% hint style="info" %}
**Allow Extend Duration** does not apply to agentic access flows. When access expires, the agent requests access again.
{% endhint %}

2. Configure any other Self Serve access flow settings according to your organization’s access policies.
3. Click **Save Access Flow**.

#### Enable MCP features and the Custom MCP

Follow these steps:

1. On the [**Account Settings**](https://app.apono.io/settings/account) page, under **AI & Automation**, click the **Enable MCP features** toggle to enable the setting. The toggle turns green.
2. On the [**MCPs**](https://app.apono.io/agentic/tools) tab, click **+ Add Custom MCP**. The **Custom MCP** panel opens.
3. On the **Config** tab, enter a **Name**.
4. From the **Resource Types** dropdown menu, select **User (custom-mcp-oauth-user)**.
5. Under **MCP Server Configuration**, click **HTTP**.
6. Enter the **Endpoint** URL for the OAuth MCP server.
7. Add OAuth headers only as required by the MCP server. Enter each header value as a constant.
   1. Under **Headers**, click **+ Add Header**.
   2. Enter a **Name** and **Value**. See table below.
   3. Repeat steps **a-b** for each header.

<table><thead><tr><th width="354.26556396484375">Name</th><th>Value</th></tr></thead><tbody><tr><td><em>APONO_OAUTH_CLIENT_ID</em></td><td><p>(Client ID) OAuth client ID Apono uses with the MCP server's authorization server</p><p>Use when the authorization server requires a pre-registered client.</p><p><strong>Example</strong>: <em>acme-mcp-client</em></p></td></tr><tr><td><em>APONO_ACCEPTED_SCOPES</em></td><td><p>Scopes the MCP server accepts</p><p>Use when the server requires specific scopes.</p><p><strong>Example</strong>: <em>billing.read,billing.write</em></p></td></tr><tr><td><em>APONO_OAUTH_DEVICE_AUTH_ENDPOINT</em></td><td><p>Device authorization endpoint of the MCP server's authorization server</p><p>Use when the authorization server requires a device authorization endpoint</p><p><strong>Example</strong>: <em>https://idp.acme.com/oauth2/device/</em></p></td></tr></tbody></table>

8. (Optional) Adjust the **Intent Policy**.
9. Click **+ Add MCP**. The panel closes. The new MCP appears under **Custom MCPs** in an enabled state.

{% hint style="info" %}
Learn more about [Model Context Protocol servers](/docs/agent-privilege-guard/apono-agent-privilege-guard-reference/model-context-protocol-mcp-servers.md).
{% endhint %}

After setup, use the [**AI Agents**](/docs/agent-privilege-guard/apono-agent-privilege-guard-reference/ai-agents.md) tab to view discovered agents and their associated users. Use the [**AI Sessions**](/docs/agent-privilege-guard/apono-agent-privilege-guard-reference/ai-sessions.md) tab to review agent activity, including access grants, tool calls, and intent policy decisions.

***

### Set up the Agentic Gateway on a local machine

{% hint style="info" %}
Learn more about [local](/docs/agent-privilege-guard/apono-agentic-gateway/install-the-local-agentic-gateway.md) and [remote](/docs/agent-privilege-guard/apono-agentic-gateway/deploy-the-remote-agentic-gateway.md) agentic gateways setups.
{% endhint %}

Each user running the gateway completes this setup on their local machine.

#### Prerequisites

<table><thead><tr><th width="200.3203125">Requirement</th><th>Details</th></tr></thead><tbody><tr><td><strong>Apono account setup completed</strong></td><td><p>Enablement of MCP feature for the Apono account</p><p>Confirm that an Apono admin has <a href="#set-up-the-apono-account">set up the Apono Account</a>:</p><ul><li>Connected the applicable integration</li><li>Created an agentic access flow with <strong>Restrict to agentic access</strong> enabled</li><li>Enabled MCP features and the custom OAuth MCP</li></ul></td></tr><tr><td><strong>Supported operating systems</strong></td><td><p>Supported operating systems:</p><ul><li>macOS</li><li>Windows 11 (native)</li><li>WSL2 (Ubuntu)</li></ul></td></tr><tr><td><strong>Node.js 20+</strong></td><td><p>Required runtime</p><p>The gateway is launched with <code>npx</code>, which runs <code>@apono-io/apono-mcp@latest</code>, downloads the gateway binary, and manages the Apono sign-in. No separate Apono CLI installation is required.</p></td></tr></tbody></table>

#### Configure your AI client

{% hint style="info" %}
If the Agentic Gateway is already configured for this client, skip to [Verify your agent](#verify-your-agent).
{% endhint %}

{% tabs %}
{% tab title="Claude Code" %}
Follow these steps:

1. Run the following command for your operating system. If this is the first run, a separate browser tab opens.

**macOS**

{% code overflow="wrap" %}

```shellscript
claude mcp add apono-agentic --npx -y @apono-io/apono-mcp@latest --agent-type claude-code
```

{% endcode %}

**Windows 11 (native)**

In Command Prompt or PowerShell:

{% code overflow="wrap" expandable="true" %}

```powershell
claude.cmd mcp add apono-agentic --npx -y @apono-io/apono-mcp@latest --agent-type claude-code
```

{% endcode %}

**WSL2 (Ubuntu)**

{% code overflow="wrap" expandable="true" %}

```shellscript
claude mcp add apono-agentic --npx -y @apono-io/apono-mcp@latest --agent-type claude-code
```

{% endcode %}

2. (First run only) Log in to Apono in the open browser tab.
   {% endtab %}

{% tab title="Claude Desktop" %}
Follow these steps:

1. In Claude, from the main navigation, click **Claude > Settings > Developer**. The **Settings** page appears.
2. Click **Edit Config**. The **claude\_desktop\_config.json** file opens.
3. Add the following configuration.

{% code overflow="wrap" %}

```json
{
  "mcpServers": {
    "apono-agentic": {
      "command": "npx",
      "args": ["-y", "@apono-io/apono-mcp@latest", "--agent-type", "claude-desktop"]
    }
  }
}
```

{% endcode %}

4. Save the file.
5. Quit and restart Claude desktop.
6. (First run only) Log in to Apono in the browser tab that opens.
   {% endtab %}

{% tab title="Cursor" %}
**Quick Start Installation**

Follow these steps:

1. Click the following button to install the MCP Server. The **MCP** page in Cursor opens.

<a href="cursor://anysphere.cursor-deeplink/mcp/install?name=apono-agentic&#x26;config=eyJjb21tYW5kIjoibnB4IC15IEBhcG9uby1pby9hcG9uby1tY3BAbGF0ZXN0IC0tYWdlbnQtdHlwZSBjdXJzb3IifQ%3D%3D" class="button primary">Add to Cursor</a>

2. Click **Install**.
3. Quit and restart Cursor.
4. (First run only) Log in to Apono in the browser tab that opens.

***

**Manual Installation**

Follow these steps:

1. In Cursor, from the main navigation, click **Tools & MCPs**. The **Tools** page appears.
2. Under **Home MCP Servers**, click **New MCP Server**. The **mcp.json** file opens.
3. Add the following configuration.

{% code overflow="wrap" %}

```json
{
  "mcpServers": {
    "apono-agentic": {
      "command": "npx",
      "args": ["-y", "@apono-io/apono-mcp@latest", "--agent-type", "cursor"]
    }
  }
}
```

{% endcode %}

4. Save the file.
5. Quit and restart Cursor.
6. (First run only) Log in to Apono in the browser tab that opens.
   {% endtab %}
   {% endtabs %}

#### Verify your agent

Perform the following tests:

1. Ask the assistant to list your available integrations. The custom MCP (OAuth) target should appear.
2. Ask it to perform an action, such as *"List my projects"*. The agent will request access through the agentic access flow.

{% hint style="info" %}
The first time a user accesses this MCP, the AI client prompts them to sign in and grant OAuth consent (if applicable). The client remembers this authorization, and all subsequent actions are performed as the authenticated user. Consent is granted separately for each MCP server.
{% endhint %}

If either task fails, [troubleshoot](#troubleshooting) your setup.

***

### Troubleshooting

#### Apono Account

<details>

<summary><strong>OAuth authorization fails</strong>.</summary>

Use any tool on the MCP server to trigger the AI client's sign-in prompt, then complete OAuth consent in the browser.

If authorization still fails, confirm the following:

* The Custom MCP (OAuth) integration is connected and healthy on the Connected tab.
* Your authorization server supports Dynamic Client Registration or a public client with PKCE.
* The [MCP settings](#enable-mcp-features-and-the-custom-mcp) on the **Config** tab are properly set.

</details>

<details>

<summary><strong>The MCP server cannot be reached</strong></summary>

Confirm the connector selected for the integration is online and can reach the endpoint.

</details>

#### Local Machine

<details>

<summary><strong>No targets or integrations are listed.</strong></summary>

Follow these steps:

1. Reauthenticate to Apono.

{% code overflow="wrap" expandable="true" %}

```shellscript
npx -y @apono-io/apono-mcp@latest login
```

{% endcode %}

2. Fully restart the AI client so the updated credentials take effect.
3. If the target is still unavailable, confirm with an Apono admin that the platform setup is complete. This includes the integration, agentic access flow, MCP feature enablement, and applicable custom OAuth MCP.
4. Follow the troubleshooting instructions in the applicable platform setup guide.

</details>

<details>

<summary><strong>More details are needed on failures.</strong></summary>

Add `--debug` to the gateway's args in your client config to enable verbose request/response logging, then check the gateway log.

</details>

<details>

<summary><strong>Configuration changes are not reflected in the agent.</strong></summary>

Fully restart the client. MCP servers are only launched at startup.

</details>


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.apono.io/docs/agent-privilege-guard/set-up-apono-agent-privilege-guard/apono-agent-privilege-guard-for-custom-oauth-mcps.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.