> 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/apono-agentic-gateway/install-the-local-agentic-gateway.md).

# Install the Local Agentic Gateway

The **Local Agentic Gateway** connects a supported AI client to Apono from the user's machine. It runs over STDIO, is launched with `npx`, and brokers agent requests and tool calls through Apono.

Configure the gateway once for each AI client or Apono account profile that you want to use. This guide covers the local installation shared by all supported platforms. For Apono account configuration, platform-specific prerequisites, and functional verification, follow the applicable Agentic Access setup guide.

{% hint style="success" icon="lightbulb" %}
To deploy the gateway centrally instead of installing it on each user's machine, see [Deploy the Remote Agentic Gateway.](/docs/agent-privilege-guard/apono-agentic-gateway/deploy-the-remote-agentic-gateway.md) The Remote Agentic Gateway is available in private beta.
{% endhint %}

***

### How the Local Agentic Gateway works

When the AI client starts the gateway for the first time:

1. **The gateway starts**. `npx` downloads and launches the Local Agentic Gateway.
2. **The user signs in to Apono**. A browser tab opens for authentication. The session is stored locally and reused until it expires.
3. **Apono registers the agent**. The agent is linked to the signed-in user and appears on the AI Agents tab.
4. **The client can send tool calls**. The gateway begins brokering requests between the AI client and Apono.

***

### Prerequisites

<table><thead><tr><th width="211.92578125">Item</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="/pages/GSGlaa9WSevBnACrmAIt">set up Apono Agent Privilege Guard</a>:</p><ul><li>Enabled MCP features</li><li>Connected the applicable integration</li><li>Created an agentic access flow with <strong>Restrict to agentic access</strong> enabled</li><li>Enabled the corresponding Apono Managed MCP</li></ul></td></tr><tr><td><strong>Platform-specific setup</strong></td><td><p>Apono Managed MCPs require additional local runtimes</p><p>Review the prerequisites in the applicable platform setup guide before connecting your AI client.</p></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><tr><td><strong>AI client</strong></td><td><p>Supported AI client</p><p>Claude Code, Claude Desktop, or Cursor are currently supported.</p></td></tr></tbody></table>

***

### Configure your AI client

{% hint style="info" %}
If the Local Agentic Gateway is already configured for this client, return to the applicable [platform setup guide](/docs/agent-privilege-guard/set-up-apono-agent-privilege-guard.md) to verify access.
{% endhint %}

Add the Local Agentic Gateway as an MCP server using the instructions for your AI client below.

{% 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 %}

#### Gateway options

Add the applicable gateway options to your AI client’s MCP configuration. Restart the client to apply any changes.

<table><thead><tr><th width="184.2939453125">Option</th><th>Description</th></tr></thead><tbody><tr><td><code>--agent-type</code></td><td><p><strong>(Required)</strong> Identifies the AI client running the gateway</p><p>The client-specific configurations above include the applicable value.</p></td></tr><tr><td><code>--debug</code></td><td>Enables verbose request and response logging while investigating a problem</td></tr></tbody></table>

***

### Verify the gateway connection

After the first successful start, confirm that the agent appears and is linked to your user on the **AI Agents** tab.

If the agent does not appear, continue to [Troubleshoot the Local Agentic Gateway](#troubleshoot-the-local-agentic-gateway).

After confirming the gateway connection, return to the applicable platform setup guide to verify platform access.

***

### Troubleshoot the Local Agentic Gateway

<details>

<summary>No targets or integrations are listed.</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>The Apono sign-in does not open or must be refreshed.</summary>

Follow these steps:

1. Start a new Apono sign-in.

{% 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.

</details>

<details>

<summary>More details are needed on failures.</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>Configuration changes are not reflected in the agent.</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/apono-agentic-gateway/install-the-local-agentic-gateway.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.