How AxiOwl Can Run as an MCP Server

How AxiOwl Can Run as an MCP Server

AxiOwl can run as a Model Context Protocol server by starting the native axiowl executable in stdio mode. In that mode, an MCP-capable host such as Codex, VS Code, Antigravity, Cursor, Claude Code CLI, Copilot CLI, or OpenCode CLI does not need to construct raw AxiOwl command lines. It asks AxiOwl for its tool list, calls a typed tool, and lets the native runtime handle sender identity, registry lookup, delivery handoff, and evidence logging.

The implementation is not a separate web service. The current server entry point is the CLI command:

axiowl mcp-server [--host <host>] [--provider <provider>]

The installed Windows path described by the installer docs is:

%LOCALAPPDATA%\AxiOwl\bin\axiowl.exe mcp-server

For Codex, the packaged MCP config runs the same binary with mcp-server --host codex --provider codex and sets AXIOWL_MCP_HOST=codex and AXIOWL_MCP_PROVIDER=codex. The remote Linux installer uses the same shape with /usr/local/bin/axiowl mcp-server --host codex --provider codex, then probes tools/list to confirm that axiowl_send_message is exposed.

The Server Contract

The native MCP server handles the normal JSON-RPC methods that an MCP host expects:

It advertises itself as AxiOwl MCP version 0.1.0 and returns an MCP tools capability during initialization. It can read newline-delimited JSON-RPC messages and framed MCP messages with Content-Length headers. The conformance test covers both formats, verifies the required tools, calls axiowl_version, and checks that an oversized frame is rejected instead of accepted silently. The frame limit in the implementation is 16 MiB.

The initialization instructions are part of the product behavior, not just documentation. They tell the host to use axiowl_send_message for sending and axiowl_create_agent for creating chats, and they explicitly warn against building raw axiowl send, axiowl create, or relay arguments inside the chat. That boundary matters because the MCP server receives host metadata that ordinary shell commands do not.

The Tools AxiOwl Exposes

The server's tools/list response is generated in mcp_server.cpp. The tool surface includes operational tools and registry tools:

The most important tool for everyday agent-to-agent work is axiowl_send_message. Its schema requires to and body, and accepts strict, runId, receiptForMessageId, and sourceContext. The tool description states a precise receipt boundary: success is an MCP-to-AxiOwl handoff receipt only. Provider delivery and a recipient reply are not implied by the MCP call returning successfully.

That is the same boundary enforced deeper in the C++ message pipeline. After AxiOwl resolves the sender and target, it records accepted_by_axiowl, sets the state to accepted_by_axiowl, logs the receipt boundary as after_target_resolution_before_delivery_worker_or_provider, and then starts the delivery-worker handoff. Provider delivery proof is later evidence. A reply through AxiOwl MCP is the stronger end-to-end proof that the target session received the message, acted on it, and sent content back with usable sender metadata.

Sender Identity Is Not a Free-Form Field

The MCP server is designed so the host session ID becomes the stable sender identity key. A chat should not invent its own session ID, and it should not manually provide --from. The server extracts identity from MCP call metadata, host configuration, provider storage, or registry state, then passes the correct internal --from and --from-node values to the CLI path.

The implementation has provider-specific identity handling. Examples include:

If required metadata is missing, the MCP send path fails loudly. For example, handle_send_message refuses to launch a no-session send when the resolved identity has no session ID. The error is intentionally specific: AxiOwl reports that the host did not provide usable session ID metadata, or that a provider-specific metadata key was missing.

When the identity is usable and has a real display name, AxiOwl can register the sender with source mcp_sender_identity. The registration stores the provider, provider session ID, node ID, raw metadata, and a sender address when that address differs from the canonical session ID. The registry lookup code then resolves a session key back to a visible sender name. If a value looks like a raw session identifier and no registry row maps it to a real display name, AxiOwl treats it as unresolved rather than pretending the raw identifier is a user-friendly sender.

Why Replies Use the MCP Tool

AxiOwl does not just deliver the sender's text. Before provider dispatch, it builds a final visible body for the recipient. If the sender is resolved, the body starts with:

Message from <sender name>

It then includes the original message and a reply instruction that tells the recipient to use the AxiOwl MCP tool:

mcp__axiowl.axiowl_send_message({
  "to": "<sender name>",
  "body": "<full reply>"
})

When available, the helper includes correlation fields such as runId and receiptForMessageId. That lets tests and operators connect a reply to a specific outbound message. If the sender cannot be resolved, the body changes to an unresolved-sender warning and no send-back command is attached. That is deliberate: AxiOwl avoids giving the recipient a broken return path.

The Codex plugin skill in the repo reinforces the same rule from the host side. It tells Codex to prefer the bundled AxiOwl MCP tool over shell commands because the tool receives Codex thread metadata. It also says not to invent sender names when metadata is missing, and not to treat send acceptance as proof of a roundtrip reply.

What This Gives Operators

Running AxiOwl as an MCP server gives operators a typed tool surface instead of a pile of ad hoc command strings. It lets the provider host supply session metadata at the moment of the tool call, while the AxiOwl runtime keeps durable identity in the registry and preserves the difference between three separate events:

  1. AxiOwl accepted the request.
  2. A provider edge accepted or rejected delivery.
  3. The recipient replied through AxiOwl with its own provider-owned identity.

That distinction is the useful part. It makes failures inspectable. A missing session ID is a metadata failure, not a mysterious delivery failure. A target that exists but is not sendable is rejected before pretending delivery happened. A returned handoff receipt is local acceptance, not a promise that a provider woke up or that a human-readable reply exists.

Closing

AxiOwl's MCP server is the native bridge between provider chats and the AxiOwl message pipeline. It exposes typed tools, reads provider session metadata, registers real sender identities, calls the same local CLI pipeline as normal AxiOwl sends, and preserves the receipt boundary between "AxiOwl accepted this" and "the recipient replied." That is why the MCP path is the preferred path for agent-to-agent AxiOwl use inside MCP-capable hosts.

Sources read

Image prompt:

Create a polished graphic image related to: AxiOwl running as an MCP server.

Subject: a compact desktop server console connected by clean glowing protocol lanes to three abstract terminal windows and a structured tool registry panel, all without readable text or logos.
Style: halfway between a clean symbolic icon and a realistic product/technical illustration; professional SaaS/technical marketing style; crisp edges; high detail; no text; no logos.
Background: solid #00ff00 chroma key green screen background covering the full canvas edge to edge.
Restrictions: no owl, no axolotl, no birds, no animals, no mascot, no text, no watermark.

Tagged