Airpost
MCP server

Connect a client

Register airpost-mcp in Claude Desktop, Claude Code or Codex, or configure any other MCP client by hand.

airpost-mcp install writes a stdio entry named airpost into the client’s config. The entry runs the airpost-mcp binary (by its full path) with --config-dir pinned to the profile it resolved, so the client always reaches the same profile.

Prerequisites

  • Airpost installed, with airpost-mcp available. See Install the CLI.
  • An Airpost engine running (open the desktop app, or run the engine as a service).

From the desktop app

Open Preferences > MCP. Under Local apps (stdio), click Connect next to Claude Desktop, Claude Code or Codex. The pane runs the bundled airpost-mcp install and shows its output. If an airpost entry that runs something else is already there, the pane offers Replace It.

Restart the client and start a new chat to see Airpost.

From the command line

airpost-mcp install --client claude-desktop

This writes mcpServers.airpost in claude_desktop_config.json:

OSFile
macOS~/Library/Application Support/Claude/claude_desktop_config.json
Windows%APPDATA%\Claude\claude_desktop_config.json
Linux$XDG_CONFIG_HOME/Claude/claude_desktop_config.json

The entry looks like this (with the desktop app, command is the airpost-mcp bundled inside the app):

claude_desktop_config.json
{
  "mcpServers": {
    "airpost": {
      "command": "/path/to/airpost-mcp",
      "args": ["--config-dir", "/Users/you/Library/Application Support/Airpost"]
    }
  }
}

Other servers in the file are left as they are. Quit and reopen Claude Desktop afterwards, then start a new chat.

Options

--clientstringrequired

claude-desktop, claude-code or codex.

--config-dirpath

The Airpost profile directory. Also read from AIRPOST_CONFIG_DIR. Without it, airpost-mcp uses the first default profile with a running engine, else the first that exists.

--config-filepath

Edit this file instead of the client’s own config.

--forceflag

Replace an airpost entry that runs something other than airpost-mcp.

--if-staleflag

Only replace the old desktop plugin’s mcp-stdio-bridge.js entry for this profile, and do nothing when there is none. The desktop app runs this once per profile after upgrading.

To remove the entry:

airpost-mcp uninstall --client claude-desktop

uninstall takes --client, --config-dir and --config-file.

install and uninstall only touch the entry named airpost. A config file that doesn’t parse is reported as an error and left alone, and an existing airpost entry that runs something other than airpost-mcp is refused unless you pass --force (uninstall always refuses it). In Codex, an airpost server written as an inline table or dotted keys is refused; remove it by hand.

Older versions of the desktop app registered an HTTP server: Codex’s [mcp_servers.airpost] with a url, and a Claude Code user-scope entry named airpost-mcp. That server no longer runs. In Codex, use Replace It or --force. In Claude Code, remove the old entry with claude mcp remove airpost-mcp --scope user.

Other MCP clients

Any client that can launch a stdio server works. Point it at the airpost-mcp binary and pass the profile directory:

JSON (mcpServers)
{
  "mcpServers": {
    "airpost": {
      "command": "/path/to/airpost-mcp",
      "args": ["--config-dir", "/path/to/airpost/profile"]
    }
  }
}

Running airpost-mcp with no subcommand serves MCP on stdio (same as airpost-mcp stdio). stdout carries the protocol; stderr is the log. Use an absolute path for command, since the client may not share your shell’s PATH.

For clients that connect to a URL instead of launching a process, use the HTTP transport.

Check the setup

airpost-mcp status

This prints the profile, the engines found, the policy in effect, the accounts agents can reach, whether HTTP is on and its port, and the paths of the audit log and token. Add --json for machine-readable output.

A typical run:

$ airpost-mcp status
Profile:   /Users/you/Library/Application Support/Airpost
Engine:    pid 48211 (0.9.0 /Users/you/Library/Application Support/Airpost/run/engine.sock), protocol 3
           a_work you@work.example (running)
           a_home you@home.example (running)
Policy:    read-write (from /Users/you/Library/Application Support/Airpost/mcp.json)
Accounts:  all
HTTP:      off (port 2587)
Audit log: /Users/you/Library/Application Support/Airpost/mcp-audit.log
Token:     /Users/you/Library/Application Support/Airpost/mcp-token

The version, socket, protocol and account states depend on your install; the layout is what status always prints. With --json, the same data comes back as an object with configDir, engines (each with file, pid, socket, engine, protocol and accounts), problems, policy, auditLog and tokenFile.

Troubleshooting

Every call, including refused ones, is in the audit log, which is often the quickest way to see what an agent tried.