Host installation

The installer reconciles three managed surfaces: MCP configuration, hook payloads and registration, and a marked instruction block. The MCP server also serves its canonical ast-mcp skill to clients that support MCP Skills. It does not install skill files automatically.

Global installation uses each host's home configuration. Managed blocks and entries have exact identities so unrelated MCP servers, hooks, and instructions remain untouched. Clients without MCP Skills support need an explicit ast-mcp skills export <destination> and host-side setup. See the skills guide.

Scope and targetsCopy Anchor Link

Install the package locally with the package manager used by the repository:

npm install --save-dev @mwillbanks/ast-mcp

Then manage local host surfaces through the stable repository-local executable:

./node_modules/.bin/ast-mcp install --scope local --target codex
./node_modules/.bin/ast-mcp update --scope local --target all
./node_modules/.bin/ast-mcp uninstall --scope local --target all

Stdio is the default. For Streamable HTTP, supply the endpoint and optionally manage it as a user service:

./node_modules/.bin/ast-mcp install \
  --scope local --target all \
  --transport http --host 127.0.0.1 --port 3768 --service

Without --service, start the printed manual command before connecting the host. update preserves an existing transport when --transport is omitted; pass an explicit transport when selected host entries disagree. Use --no-service to remove a managed service without uninstalling host entries.

For a persistent global installation:

npm install --global @mwillbanks/ast-mcp

Then manage the global host surfaces:

ast-mcp install --scope global --target claude
ast-mcp update --scope global --target all
ast-mcp uninstall --scope global --target all

Yarn 2+ should use a project-local installation because it does not provide Yarn Classic's global workflow. The package must remain installed so the configured mcp and hook subcommands can resolve native intelligence dependencies from its stable dependency tree. Binary lookup checks ancestor package bins, package metadata, package-manager global bins, and PATH. Configure runtime formatting separately with an installed formatter; see the optional formatting guide.

Local scope uses the current directory and writes ast-mcp.toml. Global scope writes project-neutral user configuration. Generated MCP definitions omit environment fields. Client roots are baseline scope hints, never authorization; version 2 top-level paths rules and user approvals remain server-authoritative. Install and update validate the applicable layered configuration before changing host files, while uninstall and config_status remain available to recover from invalid configuration.

The Bun-native server supports macOS, Linux, and Windows without a Cargo prerequisite. The installer checks the MCP handshake before reporting a healthy host surface. Restart or reconnect the server through the host after package or launch configuration changes; the host owns stdio process restarts. See the installation guide for Linux, Windows, and macOS Intel instructions, and the connection diagnosis guide when tools are unavailable.

Codex approval promptsCopy Anchor Link

Codex install and update enable MCP elicitation in top-level and named profile approval policies. A never policy becomes a granular policy that allows MCP elicitation and rejects every other approval category. Existing granular policies retain their other category values. Local installations preserve inherited global approval settings when enabling prompts.

The installer preserves on-request and legacy untrusted policies because they already allow elicitation. Malformed or unsupported approval policies stop installation before the Codex configuration is written. Uninstall retains approval policy settings.

Reconnect Codex after updating its configuration. Command-line or managed policy overrides can still prevent prompts.

Routing hooksCopy Anchor Link

Codex and Claude installations expose the same strict tool schemas, structured results, annotations, line-range compatibility, and configuration tools over stdio or Streamable HTTP. Host approvals work over stdio and legacy stateful HTTP; modern stateless HTTP fails closed for operations that require host approval.

Codex approval forms include codex_approval_kind = "mcp_tool_call" and persist = ["session", "always"]. Codex uses this metadata for its approval interface. Other clients receive standard MCP elicitation forms over stdio and legacy stateful HTTP. Modern stateless HTTP cannot establish a trusted caller session, so approval-required calls fail closed. Hosts should execute independent read-only calls concurrently when supported, while preserving sequential inspect/preview/hash/write workflows.

The installed pre-tool hook is a best-effort routing aid. It rejects direct editor tool calls and known manual write, patch, delete, and rename escape hatches so the agent is nudged toward AST intelligence and guarded file tools. It deliberately does not police Git operations, output redirection, repository scripts, or arbitrary process execution; the host agent framework and its sandbox remain responsible for execution security.