Model Context Protocol (MCP)

Xenocept ships a first-class MCP delivery mechanism for AI agents. The flagship target is Claude Code, but the same machinery works for any MCP-compatible agent.

There are two modes: channel mode (push) and polling mode (pull). Pick the one that matches your environment.

Channel Mode (Push)

In channel mode, the xenocept binary runs in a special MCP channel server mode as a subprocess of your AI agent. SSE events from the running Xenocept GUI flow through the channel and become inline notifications in your agent’s session.

Architecture

┌───────────────────────────────────────────────┐
│ Xenocept GUI (xenocept, port 9500) │
│ - SSE server: /api/v1/channels/events │
│ - HTTP send: /api/v1/channels/send │
│ - Channel registry: name → SSE connection │
└───────────────┬───────────────────────────────┘
                │ SSE (filtered by channel name)
                ▼
┌───────────────────────────────────────────────┐
│ xenocept --mcp <ChannelName> │
│ - SSE client (subscribes by name) │
│ - MCP stdio server (channel capability) │
└───────────────┬───────────────────────────────┘
                │ stdio MCP (JSON-RPC)
                ▼
┌───────────────────────────────────────────────┐
│ Claude Code session (user's terminal) │
└───────────────────────────────────────────────┘

Launching the Channel Server

The same xenocept binary handles both the GUI and the MCP channel server. To run it in channel mode, invoke it with --mcp:

xenocept --mcp MyChannelName

When invoked this way, Xenocept does not open a window or sit in the tray. It runs as a stdio MCP server, subscribes to the Xenocept GUI over SSE filtered by MyChannelName, and forwards events into the MCP session as inline notifications.

The channel name is any UTF-8 string you choose. It identifies this MCP session in the Xenocept GUI — the GUI’s “Send to Channel” UI lets you pick which channel a snapshot goes to.

Wiring It Into Claude Code

Add Xenocept as an MCP server in your Claude Code project’s .mcp.json:

{
  "mcpServers": {
    "xenocept": {
      "command": "/path/to/xenocept",
      "args": ["--mcp", "MyChannelName"]
    }
  }
}

Restart Claude Code. The next time you press Submit in the Xenocept GUI and choose “MyChannelName” as the destination, the snapshot arrives inline in your active Claude session.

Multiple Channels

You can run multiple --mcp instances at once, each with a different channel name. Each Claude Code project (or window, or session) gets its own channel. The Xenocept GUI’s “Send to Channel” dropdown lists every currently-active channel.

Other Options

The channel name accepts any UTF-8 string that round-trips through percent-encoding (emoji and spaces are fine). Leading/trailing whitespace is trimmed. Empty names are rejected with a clear error.

Polling Mode (Pull)

If you don’t want to install a channel server — or your agent doesn’t support an external MCP server — you can use polling mode instead.

In polling mode, your agent pulls snapshots from the Xenocept HTTP API on a schedule (typically every few seconds, or whenever the user asks it to check). No subprocess, no SSE, no channel — just HTTP.

Endpoints

The session JSON shape is documented in Session JSON Schema.

When Polling Is the Right Choice

• You don’t want to install or run a separate --mcp subprocess.
• Your agent already polls for state on a regular cadence.
• You’re integrating Xenocept into a tool that doesn’t speak MCP at all.

When Channel Mode Is Better

• You want zero-latency delivery (push, not pull).
• The agent is already running long-lived and can host an MCP server.
• You want the snapshot to appear inline in the agent’s session without the agent having to ask.

The Session Inside the MCP Session

When an MCP-delivered session lands, the agent sees the session JSON plus the image attachments. How it’s surfaced depends on the agent — Claude Code, for example, can render the focus images directly into the conversation with the comment text as commentary.

The structured nature of the session (Notes with focus rectangles and side-anchored text) is what makes this useful: the agent isn’t squinting at a flat screenshot and guessing what the user meant. The annotation is the structure.