> 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-tools.md).

# Apono Agent Privilege Guard for Custom Tools

Set up Apono Agent Privilege Guard for custom MCP and OAuth tools to give AI agents controlled, temporary access to your organization's applications and services.

An Apono admin configures the custom OAuth integration, an agentic access flow, and the custom MCP. Each user then connects a supported AI client through the Local Agentic Gateway, which brokers requests between the AI client, Apono, and your custom tool.

***

### Set up the Apono account

An Apono admin completes this setup once.

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

#### Prerequisite

<table><thead><tr><th width="200.3828125">Requirement</th><th>Details</th></tr></thead><tbody><tr><td><strong>Custom MCP integration</strong></td><td><p>Connected Apono integration</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 MCP integration is connected, follow the <a href="/pages/SlkVw3yOMtL9JsNgtlYg">Custom integration docs</a>.</p></td></tr></tbody></table>

#### Create an agentic access flow

Create a Self Serve access flow that allows agents to request temporary access to an Atlassian instance 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</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 your Atlassian integration, 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, under **Apono Managed Tools**, click the toggle on your desired **Custom MCP** card to enable the tool.

{% 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 Mixpanel 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 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 your custom 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.
{% endhint %}

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

***

### Troubleshooting

#### Apono Account

<details>

<summary><strong>(If applicable) OAuth authorization fails</strong>.</summary>

Use any action supported by the custom tool to trigger the AI client's sign-in prompt, then complete the OAuth consent in your browser. If authorization still fails, confirm with your administrator that both the [custom MCP integration](/docs/additional-integrations/mcps/custom-mcp.md) and the [custom MCP](#enable-mcp-features-and-the-custom-mcp) are enabled.

</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 Apono Managed 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-tools.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.