Airpost
MCP server

HTTP transport

Serve airpost-mcp over MCP's streamable HTTP transport with a bearer token, optionally as a background service.

airpost-mcp http serves MCP’s streamable HTTP transport at http://127.0.0.1:<port>/mcp. Use it for clients that connect to a URL instead of launching a process. airpost-mcp install only writes stdio entries, so you configure HTTP clients by hand.

Turn it on

HTTP serves only when http.enabled is true in mcp.json. In the desktop app, open Preferences > MCP and turn on Allow apps over HTTP. The pane writes http.enabled, installs the background service, and shows the URL and the Access key.

To do it from the command line, set "http": {"enabled": true, "port": 2587} in <config-dir>/mcp.json (see Access levels), then run the server:

airpost-mcp http --port 2587

It logs [airpost-mcp] listening on http://127.0.0.1:2587/mcp to stderr and serves until stopped. With HTTP off in the policy it exits at once with:

[airpost-mcp] HTTP is off; set "http": {"enabled": true} in <config-dir>/mcp.json

If you switch HTTP off while the server is running, it keeps listening but refuses every tool call until you switch it back on.

--portnumber

The port. Defaults to http.port in mcp.json (2587).

--bindstringdefault:127.0.0.1

The address to listen on. Also AIRPOST_MCP_BIND. Anything other than loopback belongs behind a TLS proxy.

--allowed-hoststring

A Host header to accept besides the loopback names, such as the proxy’s public name. Repeatable. Also AIRPOST_MCP_ALLOWED_HOSTS, comma-separated.

--config-dirpath

The Airpost profile directory. Also AIRPOST_CONFIG_DIR.

Authentication

Every request needs Authorization: Bearer <token>. The token is stored in <config-dir>/mcp-token, created owner-only (0600) the first time it’s needed. Print it with:

airpost-mcp token

The server answers:

StatusWhen
404 {"error":"Not found"}Any path other than /mcp
401 {"error":"Unauthorized"}No Authorization header, or the wrong token
403The Host header isn’t allowed (see below)

Requests whose Host isn’t a loopback name or an --allowed-host get a 403, which blocks DNS rebinding from a browser.

A client config usually looks like this (the exact keys depend on the client):

{
  "mcpServers": {
    "airpost": {
      "type": "http",
      "url": "http://127.0.0.1:2587/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

To check the server and token by hand, send an MCP initialize:

curl -s http://127.0.0.1:2587/mcp \
  -H "Authorization: Bearer $(airpost-mcp token)" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

A working server answers with its server info and instructions. The response’s Mcp-Session-Id header names the session; a client sends it back on later requests. The clientInfo name you send is what the audit log records as client.

To change the token, delete <config-dir>/mcp-token and run airpost-mcp token again; then update every client that uses it. Over HTTP, the policy is the same as over stdio, apart from the switch: access level, hidden accounts and folders, and the audit log all apply.

Over HTTP, create_draft, reply_to_thread and update_draft refuse attachments, whatever address the server is bound to, because attaching reads files on the server’s machine. Removing attachments still works.

Run it as a service

airpost mcp-http install installs a launchd (macOS) or systemd (Linux) user unit that listens on 127.0.0.1 and starts airpost-mcp http on the first connection. It needs http.enabled in mcp.json.

airpost mcp-http install --port 2587

See Services for the full set of mcp-http subcommands and options.

Health check

airpost-mcp healthcheck --port 2587

Exits 0 when airpost-mcp http answers on 127.0.0.1. It’s meant for containers that don’t have curl.

On a server

To serve agents from a self-hosted Airpost server, bind to every interface behind a TLS proxy and accept the proxy’s host name:

AIRPOST_MCP_BIND=0.0.0.0 \
AIRPOST_MCP_ALLOWED_HOSTS=airpost.example.com \
airpost-mcp http

See Airpost server for the server setup.

Troubleshooting