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.

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.

---

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

Requirement	Details
OAuth MCP integration	Connected Apono integration for this OAuth MCP server Verify that the integration exists and is healthy on the Connected tab. If no custom OAuth MCP integration is connected, follow the Custom MCP (OAuth) integration docs.
OAuth authorization	Authorization server that supports either Dynamic Client Registration (DCR) or a pre-registered public client with PKCE Additional information: OAuth client ID for a pre-registered client Accepted scopes, if required by the server Device authorization endpoint, if required by the server IMPORTANT: Client-secret authentication and other OAuth methods are not supported.

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 to define the requestors, resources, access duration, and approval process. As you create the flow, apply the following settings for agentic access.

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

Allow Extend Duration does not apply to agentic access flows. When access expires, the agent requests access again.

1. Configure any other Self Serve access flow settings according to your organization’s access policies.

2. Click Save Access Flow.

Enable MCP features and the Custom MCP

Follow these steps:

1. On the Account Settings page, under AI & Automation, click the Enable MCP features toggle to enable the setting. The toggle turns green.

2. On the MCPs 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.

Name	Value
APONO_OAUTH_CLIENT_ID	(Client ID) OAuth client ID Apono uses with the MCP server's authorization server Use when the authorization server requires a pre-registered client. Example: acme-mcp-client
APONO_ACCEPTED_SCOPES	Scopes the MCP server accepts Use when the server requires specific scopes. Example: billing.read,billing.write
APONO_OAUTH_DEVICE_AUTH_ENDPOINT	Device authorization endpoint of the MCP server's authorization server Use when the authorization server requires a device authorization endpoint Example: https://idp.acme.com/oauth2/device/

1. (Optional) Adjust the Intent Policy.

2. Click + Add MCP. The panel closes. The new MCP appears under Custom MCPs in an enabled state.

Learn more about Model Context Protocol servers.

After setup, use the AI Agents tab to view discovered agents and their associated users. Use the AI Sessions tab to review agent activity, including access grants, tool calls, and intent policy decisions.

---

Set up the Agentic Gateway on a local machine

Learn more about local and remote agentic gateways setups.

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

Prerequisites

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

Configure your AI client

If the Agentic Gateway is already configured for this client, skip to Verify your agent.

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

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

Windows 11 (native)

In Command Prompt or PowerShell:

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

WSL2 (Ubuntu)

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

1. (First run only) Log in to Apono in the open browser tab.

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.

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

1. Save the file.

2. Quit and restart Claude desktop.

3. (First run only) Log in to Apono in the browser tab that opens.

Cursor

Quick Start Installation

Follow these steps:

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

Add to Cursor

1. Click Install.

2. Quit and restart Cursor.

3. (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.

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

1. Save the file.

2. Quit and restart Cursor.

3. (First run only) Log in to Apono in the browser tab that opens.

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.

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.

If either task fails, troubleshoot your setup.

---

Troubleshooting

Apono Account

OAuth authorization fails.

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 on the Config tab are properly set.

The MCP server cannot be reached

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

Local Machine

No targets or integrations are listed.

Follow these steps:

1. Reauthenticate to Apono.

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

1. Fully restart the AI client so the updated credentials take effect.

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

3. Follow the troubleshooting instructions in the applicable platform setup guide.

More details are needed on failures.

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

Configuration changes are not reflected in the agent.

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