aai:exec
Execute any AAI tool action. Read the guide first (call app:*, mcp:import, skill:import, or search:discover) — it contains the required schema and parameters.
LABSCO SUMMARY
Ten servers stop costing ten tool lists in every conversation.
The trade is deliberate: each app contributes a one-line summary up front and its real schema only when it is called, which keeps a large collection of servers usable at the cost of one extra hop through aai:exec. The second benefit is quieter but adds up — an import is shared across every agent on the machine, so Claude Code, Codex and OpenCode stop each keeping their own copy of the same configuration.
What it is
A management layer in front of your other MCP servers and skills. Each import becomes an Agent App represented by a short summary in the session; the details are fetched when the app is actually called, and imports are shared across agents rather than configured per client.
What you get
- mcp:import brings an MCP server in as a global app, and skill:import does the same for a local skill — both return the import guide first, so the shape of the call is not guesswork
- aai:exec is the single entry point that runs any action on any imported app
- search:discover finds and installs new tools during a conversation, which is what turns "I need a browser automation tool" into an installed one without a restart
- listAllAaiApps shows what is imported for the current agent, and enableApp and disableApp turn one on or off for that agent alone
- removeApp deletes an import from every agent, behind an explicit confirm
- getAppConfig returns an app's full configuration plus ready-to-share install snippets
- updateAppConfig changes one field of an imported server — an argument, a timeout, an environment variable, a transport — and preserves the rest, so a single parameter can be fixed without re-entering the whole config
Requirements
No account and no key of its own — each imported app still needs whatever credentials it needs. It runs as npx -y aai-gateway over stdio, and the README gives the one-line add commands for Claude Code, Codex and OpenCode, plus a plugin for OpenClaw. Imports it manages are global, so project-scoped servers still belong in your agent's own config (.mcp.json, .cursor/mcp.json) and project-scoped skills in its skill directory.
Setup effort
One command — claude mcp add --scope user --transport stdio aai-gateway -- npx -y aai-gateway
USE CASES
01
Running many MCP servers without every tool list riding along
Import them once, and each shows up as a short summary until the moment it is used.
02
Getting a capability you do not have yet, mid-task
Search for a tool that fits the request, install it and use it in the same conversation — no restart.
03
Using the same setup from a different agent
Import once through the gateway; other agents on the machine see the same apps rather than needing their own configuration.
04
Fixing one setting on a server that is misbehaving
Read its configuration, change just the argument, environment variable or timeout that is wrong, and leave the rest untouched.
05
Trimming what one agent can reach
Disable the apps that agent should not use, and remove the ones nobody needs any more.
10 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
disableApp
Disable one app for the current agent only. If you do not know the app id, call listAllAaiApps first to find it.
enableApp
Enable or re-enable an app for the current agent. When the user asks to enable, start, turn on, or use a specific app by name, call listAllAaiApps first to check if it is already imported before searching for new tools.
getAppConfig
Get the full configuration of an imported app plus ready-to-share install snippets. Use this when: (1) the user wants to inspect or check an app's config, or (2) the user wants to share an app's install instructions with someone else (e.g. via chat or email). Secrets are masked as ${VAR_NAME} and required env vars are listed. Works for both MCP and skill apps. If you do not know the app id, call listAllAaiApps first.
listAllAaiApps
List imported apps (MCP servers and skills) for the current agent. This does not include built-in tools like search:discover, mcp:import, or skill:import — those are always available.
mcp:import
Import an MCP server as a GLOBAL app (visible to all projects). For project-level MCP, use your agent's native config instead (e.g. .mcp.json, .cursor/mcp.json). Call this first to get the import guide. Never ask the user for API keys or secrets in chat.
removeApp
Remove one AAI Gateway managed import from all agents. If you do not know the app id, call listAllAaiApps first to find it.
search:discover
Find and install new tools. Call this when: 1. The user explicitly asks to search for or install tools. 2. The user's request cannot be fulfilled by any currently available tool — proactively suggest and search for a suitable tool. Before searching, check listAllAaiApps first — the user may already have the app imported (possibly disabled).
skill:import
Import a local skill as a GLOBAL app (visible to all projects). For project-level skills, use your agent's native skill directory instead (e.g. .claude/skills/). Call this first to get the import guide.
updateAppConfig
Update an imported MCP server's configuration. Only provided fields are applied; all others are preserved — so the user can change a single parameter (e.g. add an arg, set a timeout) without re-entering the whole config. Use this instead of remove + re-import when modifying an existing MCP. Only MCP apps are supported (not skills). Env and headers, when provided, replace the existing values. After updating, call the app to verify it still works. If you do not know the app id, call listAllAaiApps first.
BEFORE YOU INSTALL
What to know first
Tools you get
10 tools when we connected. Each imported Agent App adds its own app_<app-id> tool, so the count grows as you import apps. skill:create, named in an architecture doc, is not available.
Requires
npx on PATH
CONTEXT COST
Light Standing cost
Rated by the size of the 10 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Server setup
Claude Code
TERMINAL
claude mcp add --scope user --transport stdio aai-gateway -- npx -y aai-gatewayMCP Clients
Codex
CODEX · TERMINAL
codex mcp add aai-gateway -- npx -y aai-gatewayOpenCode
OPENCODE · JSON
{
"mcp": {
"aai-gateway": {
"type": "local",
"command": [
"npx",
"-y",
"aai-gateway"
],
"enabled": true
}
}
}OpenClaw
OPENCLAW · TERMINAL
openclaw plugins install openclaw-aai-gateway-plugin
