Context Retrieval

The MCP tools

Waypoint exposes two MCP tools via the server's MCP endpoint (/api/mcp):

get_waypoint_context — retrieves the history of past sessions that touched a specific file.

get_waypoint_context("src/billing/invoice.ts")

list_waypoints — lists recent sessions across the whole repo, useful at session start to understand what was worked on recently.

list_waypoints()

Both tools are automatically available after waypoint init configures your agent to connect to the Waypoint server's MCP endpoint. The connection is persistent across sessions — you don't need to manually start anything.

How it works

The MCP endpoint on the Waypoint server handles requests from your agent (Claude Code, Copilot, Codex, or CLI). Your agent is configured with the server URL and API key:

{
  "mcpServers": {
    "waypoint": {
      "type": "http",
      "url": "https://your-waypoint-server.com/api/mcp",
      "headers": {
        "Authorization": "Bearer wp_..."
      }
    }
  }
}

The /api/mcp endpoint uses HTTP JSON-RPC 2.0 to handle tool calls from your agent. If no server is configured, the tools return an error prompting you to run waypoint connect.

What get_waypoint_context returns

By default, the tool returns a compact summary for each past session that touched the file:

**Session a1b2c3d4** (2026-05-31) · joe · `7699987`
- **Intent:** replace Redis session middleware with JWT — latency under load
- **Modified:** lib/auth.ts, middleware.ts, app/api/auth/login/route.ts
- **Failed:** pnpm test auth (exit 1)
- **Plan (3/4 done):** [x] add JWT helpers | [x] update middleware | [x] login endpoint | [ ] refresh endpoint

Each bullet is derived mechanically from the event log — no AI summarisation at the server:

The agent synthesises what is relevant to the current task — a failed approach from six months ago is weighted differently than one from yesterday.

Full event log

Pass full: true to get a timestamped event timeline instead:

get_waypoint_context("src/auth/middleware.ts", full=true)

Full mode includes every user_prompt, file_edit, bash_command, and agent_plan event in chronological order. Use this when the summary omits context you need — for example, to see the exact commands that failed or the full task list.

How the agent uses it

The instruction written to CLAUDE.md by waypoint init tells the agent:

Before working on any file, call get_waypoint_context(filepath) to retrieve the development history for that file. This tells you what was tried before, why decisions were made, and what not to repeat.

At session start, call list_waypoints to see what was worked on recently.

The agent synthesises the returned events at query time. Because raw events are returned (not pre-digested summaries), the agent can weight what's relevant to the current task — a failed approach from six months ago matters differently than one from yesterday.

Server lookup

Both tools query the Waypoint server:

GET /api/sessions/context?filepath=src/billing/invoice.ts
Authorization: Bearer <apiKey>

The server returns sessions from the whole team — sessions you didn't personally run. This is the primary value of the server: shared context across the entire team. A decision made by one developer's agent session is immediately available to every other developer.

Scope of results

get_waypoint_context returns the limit most recent sessions that touched the file (default: 3, max: 10). Increasing this gives the agent more history but also more noise. Three recent sessions covers the vast majority of relevant context.

What to expect

The first time you query a file that was touched before Waypoint was installed, there's no history — the tool returns an empty result. History accumulates as sessions run. Within a few days of normal use on an active project, most frequently-edited files will have meaningful context.