Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Install the Local Agentic Gateway

Connect an AI client to Apono from a user’s machine

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.

This guide covers the local installation for supported AI clients and operating systems. For Apono account configuration, platform-specific prerequisites, and functional verification, follow the applicable Agentic Access setup guide.


How the Local Agentic Gateway works

During initial setup and first use, the Local Agentic Gateway performs the following operations:

  1. The gateway starts. npx downloads and launches the Local Agentic Gateway.

  2. The user signs in to Apono. With the quick start installation, the installer signs you in during installation. With manual installation, 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

Item
Details

Apono account setup completed

Enablement of MCP feature for the Apono account

Confirm that an Apono admin has set up Apono Agent Privilege Guard:

  • Enabled MCP features

  • Connected the applicable integration

  • Created an agentic access flow with Restrict to agentic access enabled

  • Enabled the corresponding Apono Managed MCP

Platform-specific setup

Apono Managed MCPs require additional local runtimes

Review the prerequisites in the applicable platform setup guide before connecting your AI client.

Supported operating systems

Supported operating systems:

  • macOS, Linux

  • 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. When using the quick start installation below, the installer checks for Node.js 20+ and npx but does not install them. If either is missing, the installer provides the applicable installation command and exits without making changes.

AI client

Supported AI client

Claude Code, Claude Desktop, and Cursor are currently supported.


Configure your AI client

If the Local Agentic Gateway is already configured for this client, return to the applicable platform setup guide to verify access.

To connect your AI client to Apono, configure the Local Agentic Gateway as an MCP server.

Choose one of the following installation methods based on your environment and preferred setup approach:

Quick start installation

The quick start installation uses a single shell command to install the Local Agentic Gateway and configure supported AI clients installed on your machine.

The installer:

  • Checks for installation prerequisites

  • Registers any detected Claude Code, Claude Desktop, and Cursor installations

  • Warns about a directory-scoped Claude Code entry that would hide the new one

  • Signs you in

  • Offers the credential guardrails

Follow these steps:

  1. Run the shell command for your operating system.

Run the installer once from within Windows Subsystem for Linux (WSL). It configures Claude Code in Linux and Claude Desktop and Cursor on Windows, with all three clients sharing one Apono sign-in. Claude Desktop and Cursor launch the gateway through WSL.

Do not run the Windows 11 installer separately.

If WSL_DISTRO_NAME is not set, Windows clients launch the gateway in your default WSL distribution. The installer displays a warning when this occurs.

In PowerShell:

  1. At the end of the installation, choose whether to apply the optional credential guardrails.

Optional credential guardrails are written to client configuration files (including settings.json) to prevent AI clients from accessing local cloud credentials.

  • Claude Code: Adds deny rules for ~/.aws/**, ~/.kube/config, aws, and aws-vault

  • Cursor: Adds instructions to refuse the same commands

The installer requests permission before modifying configurations, preserves existing settings, and backs up modified files.

These guardrails rely on AI-client behavior and are not enforced by the operating system.

Manual installation

Manual installation lets you configure the Local Agentic Gateway for individual AI clients using their respective MCP setup methods.

Depending on the AI client, setup involves:

  • Adding the gateway as an MCP server using a command, configuration file, or installation link

  • Restarting the AI client, if required, to apply the configuration

  • Signing in to Apono when the gateway starts for the first time

Select your AI client below and follow the installation instructions.

Follow these steps:

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

macOS

Windows 11 (native)

In Command Prompt or PowerShell:

WSL2 (Ubuntu)

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

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.

  1. Save the file.

  2. Quit and restart Claude desktop.

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

Installation link

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.


Configuration file

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.

  1. Save the file.

  2. Quit and restart Cursor.

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

Gateway options

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

Option
Description

--agent-type

(Required) Identifies the AI client running the gateway

The client-specific configurations above include the applicable value.

--debug

Enables verbose request and response logging while investigating a problem


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.

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


Troubleshoot the Local Agentic Gateway

No targets or integrations are listed.

Follow these steps:

  1. Reauthenticate to Apono.

  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 Apono Managed MCP.

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

The gateway is registered but the agent does not appear in Claude Code.

Claude Code prioritizes project-specific MCP server configurations over user-level configurations. An existing apono-agentic entry in a project directory can therefore override the entry created by the installer.

The installer identifies affected directories. From each affected directory, run claude mcp remove apono-agentic -s local to remove the old entry. Then start a new Claude Code session.

Claude Desktop was skipped on Windows.

If Claude Desktop was installed from the Microsoft Store but never opened, it has no config file yet. Open it once, then run the installer again.

The Apono sign-in does not open or must be refreshed.

Follow these steps:

  1. Start a new Apono sign-in.

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

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.

Last updated

Was this helpful?