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.
The port. Defaults to http.port in mcp.json (2587).
The address to listen on. Also AIRPOST_MCP_BIND. Anything other than loopback belongs behind a TLS proxy.
A Host header to accept besides the loopback names, such as the proxy’s public name. Repeatable. Also AIRPOST_MCP_ALLOWED_HOSTS, comma-separated.
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:
| Status | When |
|---|---|
404 {"error":"Not found"} | Any path other than /mcp |
401 {"error":"Unauthorized"} | No Authorization header, or the wrong token |
| 403 | The 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.