Agent Setup

Start the installed server

Start Waypoint after installing it from a GitHub Release or npm. The local server listens on IPv4 loopback.

waypoint start

Give your agent the Waypoint workflow

Install the recommended Waypoint skill in each coding-agent harness that will handle Annotations. The Skills CLI detects supported agents and lets you choose the destinations. This gives the agent Waypoint’s workflow guidance; connect MCP next so it can reach the local Queue.

npx skills@latest add logbookfordevs/logbook-waypoint --skill waypoint --global

Add Waypoint to supported agents

Add MCP can detect supported coding agents and guide you through the configuration it will update. It configures the connection but does not install or start Waypoint.

npx add-mcp http://127.0.0.1:3846/mcp --name logbook-waypoint --global

Verify the connection with one request

After configuring MCP, reload or reconnect your agent’s MCP tools if your client requires it. Run waypoint status to check the local server, then ask the agent to read Waypoint for the URL open in your browser.

A successful connection returns your saved Annotations, or an empty result when that URL has no work yet. An empty Queue is not a connection failure. Save a test Annotation on that page and ask again; the agent should be able to report your comment.

Your app’s port and Waypoint’s port serve different purposes: use your app URL to identify the work, and http://127.0.0.1:3846/mcp to configure the tool connection.

Use the project root, such as http://localhost:3000/, to read across the project. A path such as /account narrows the request to that page; including a query or hash narrows it to that captured view, such as a particular filter or tab.

Read my Waypoint annotations for http://localhost:3000/. Tell me what is pending before changing anything.

Keep a foreground Watch

Agent harnesses that surface background command output can keep the Waypoint CLI Watch running while implementation continues. Structured mode emits one complete current open-work snapshot per line and reconnects through the durable Watch journal. Read a selected ID through MCP for its Survey context.

The command retrieves activity without creating or renewing Claims. It cannot guarantee that an idle agent wakes up: scheduling attention remains the responsibility of the coding-agent harness.

waypoint watch http://localhost:3000/ --json

Connect Codex

Add the local streamable HTTP endpoint to Codex configuration. The server remains on IPv4 loopback and does not require a LAN binding.

[mcp_servers.logbook-waypoint]
url = "http://127.0.0.1:3846/mcp"

Connect another MCP client

JSON-based clients can register the same provider-neutral endpoint. Pi, OpenCode, and other MCP-compatible agents may present the setting in different places, but Waypoint’s tools and lifecycle do not change.

{
  "mcpServers": {
    "logbook-waypoint": {
      "url": "http://127.0.0.1:3846/mcp"
    }
  }
}

Explore the MCP tool surface

Open the Signal Chart for a visual explanation of how work travels from Annotation to Queue to agent. Its MCP tool map may lag the current CLI Watch interface.