---
name: aos-gateway
description: >-
  Local MCP gateway and per-app MCP picks. Use when checking, starting, enabling the gateway, or debugging why an MCP server is direct or shared.
category: bdb-core
risk: safe
tools:
- claude-code
- opencode
---

# aos-gateway

The gateway is a local token-checking forwarder (`127.0.0.1:7790`) in front of `@1mcp/agent` (`127.0.0.1:7791`). Harness MCP files get one `aos` entry instead of many servers. Full reference (repo, not installed): https://github.com/hybridlabor-api/aos/blob/main/docs/mcp-gateway.md.

## Commands

```
aos-gateway serve | start | stop | restart | status [--json] | enable | direct | adopt [--dry-run] [--json]
```

- **Check:** `aos-gateway status` (exit 0 only when running). Upstream health is the state of 1mcp as a whole, not per server.
- **Enable:** `aos-gateway enable` points the harness MCP files at the gateway. **Direct:** `aos-gateway direct` reverses it and restores removed entries.
- **Start/stop/restart:** launchd on macOS. Windows (`schtasks`) is UNVERIFIED in the code. Elsewhere run `aos-gateway serve`.
- Config lives in `~/.agents/gateway/` (`token`, `upstream_template.json`). `token` must be mode 600. Never print or copy its content.

## Adopt

1. Run `aos-gateway adopt --dry-run` first and show the result.
2. Run `aos-gateway adopt` only after the human agrees. It edits harness MCP files.
3. Run `aos-gateway restart` afterwards.

Adopt skips remote (url/http/sse) entries, disabled ones, names the AOS install owns, names over 26 chars, entries with inline secrets and conflicting definitions. Secrets are never copied.

## Allow list vs direct

- Shared through the gateway: `github`, `open_design_mcp`, `bdb_resolume_mcp`, `bdb_grandma3_mcp`, `bdb_blender_mcp`, `bdb_davinci_mcp`, `adobe_uxp_mcp`, `bdb_unreal_mcp`, `bdb_after_effects_mcp`.
- Everything else stays direct (for example `deja`, `memb_mcp`, `mcsc`, `openwiki`, `bdb_td_minddesigner`, the official picks). A shipped entry with `shared: false` also stays direct.
- Do not add a server to the allow list by hand. It is defined in `lib/gateway/config.js`.

## Node for After Effects

`bdb_after_effects_mcp` needs Node >= 24. `aos-gateway serve` warns on an older Node and the AE upstream will not start. Fix the Node version, then restart the gateway.

## One MCP per app

`mcp_picks.json` keeps the first satisfied candidate per app and removes the others.

- Blender: `bdb_blender_official_mcp` when Blender >= 5.1 is found, else `bdb_blender_mcp`.
- Resolume: `bdb_resolume_official_mcp` when the Arena `mcp/resolume_arena_mcp_server` binary is found, else `bdb_resolume_mcp`.
- After Effects: `bdb_after_effects_mcp_legacy` only with `AOS_AE_MCP=legacy`, else `bdb_after_effects_mcp`.

## Limits

- The token stops browsers, not local processes.
- Do not edit `~/.agents/gateway/` files by hand. Use the commands above.