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:
The gateway starts.
npxdownloads and launches the Local Agentic Gateway.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.
Apono registers the agent. The agent is linked to the signed-in user and appears on the AI Agents tab.
The client can send tool calls. The gateway begins brokering requests between the AI client and Apono.
Prerequisites
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
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: (Recommended) Automatically configure supported AI clients installed on your machine
Manual installation: Configure selected AI clients individually using client-specific instructions
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:
Run the shell command for your operating system.
In PowerShell:
At the end of the installation, choose whether to apply the optional credential guardrails.
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:
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)
(First run only) Log in to Apono in the open browser tab.
Follow these steps:
In Claude, from the main navigation, click Claude > Settings > Developer. The Settings page appears.
Click Edit Config. The claude_desktop_config.json file opens.
Add the following configuration.
Save the file.
Quit and restart Claude desktop.
(First run only) Log in to Apono in the browser tab that opens.
Installation link
Follow these steps:
Click the following button to install the MCP Server. The MCP page in Cursor opens.
Click Install.
Quit and restart Cursor.
(First run only) Log in to Apono in the browser tab that opens.
Configuration file
Follow these steps:
In Cursor, from the main navigation, click Tools & MCPs. The Tools page appears.
Under Home MCP Servers, click New MCP Server. The mcp.json file opens.
Add the following configuration.
Save the file.
Quit and restart Cursor.
(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.
--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
Last updated
Was this helpful?
