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.

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.

To deploy the gateway centrally instead of installing it on each user's machine, see Deploy the Remote Agentic Gateway. The Remote Agentic Gateway is available in private beta.

---

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

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.
macOS	Supported operating system The Local Agentic Gateway is currently supported on macOS.
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.
AI client	Supported AI client Claude Code, Claude Desktop, or 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.

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

Claude Code

Follow these steps:

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

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

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.

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.
--profile	Connects the client to a specific Apono account profile To connect multiple accounts, create a separate MCP server entry with a unique profile value for each account.
--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.

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

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

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

Follow these steps:

1. Start a new Apono sign-in.

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

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.