MCP server

Windrunner exposes a Model Context Protocol server for AI clients that need to read workspace information or propose reviewed changes to project work.

Endpoint and transport

Setting	Value
URL	http://localhost:8066/mcp
Transport	Streamable HTTP (stateless)
Auth	Authorization: Bearer <API key> — same keys as the REST API

Enable/disable with WINDRUNNER_MCP_ENABLED (true by default).

Connect a client

Codex CLI:

Terminal

codex mcp add windrunner \
  --url http://localhost:8066/mcp \
  --header "Authorization: Bearer wr_k_..."

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "windrunner": {
      "type": "http",
      "url": "http://localhost:8066/mcp",
      "headers": {
        "Authorization": "Bearer wr_k_..."
      }
    }
  }
}

Available tools

Read tools:

Tool	Scope required	Description
list_projects	projects:read	A bounded, paginated page of projects visible to the key owner
list_teams	teams:read	Bounded team candidates, optionally filtered by query
get_team	teams:read	One team's name and description
list_team_members	team_members:read	A bounded, paginated team-member page with title, bio, and role
list_team_projects	team_projects:read	A bounded, paginated page of projects linked to a team
list_users	users:read	Bounded active-user candidates, optionally filtered by query
get_user	users:read	One active user's identity, title, and bio
search_work_items	work_items:read	Search a project's work items, entries, and relationship reasons
list_work_items	work_items:read	A bounded, paginated work-item page for a project
get_work_item	work_items:read + entries:read + relationships:read	One selected item plus the first bounded pages of entries and relationships
list_entries	entries:read	A bounded, paginated entry page for a project or work item
search_entries	entries:read	Ranked entry candidates, or an exact body duplicate check within one work item
list_relationships	relationships:read	A bounded, paginated relationship page for a project or entity
find_relationships_exact	relationships:read	Exact endpoint-and-type relationship lookup
list_project_blockers	work_items:read + relationships:read	Server-side blocker results with bounded pagination
get_project_summary	projects:read + work_items:read + entries:read + relationships:read	Server-side project totals and distributions
list_my_work	(any valid key)	A bounded, paginated page of items assigned to the key owner
get_attention_summary	work_items:read + notifications:read	Bounded overdue, blocked, due-soon, new-assignment, and unread-notification sections for the key owner
get_work_item_timeline	work_items:read	The latest significant lifecycle events for one work item
list_project_assignees	project_access:read + users:read + teams:read	Bounded users and teams eligible for assignment in one project
get_team_workload	teams:read + team_members:read + work_items:read + calendar_events:read	Read-only team workload comparison for an inclusive range of up to 31 days

Proposal tools:

Tool	Scope required	Description
propose_workspace_changes	projects:read plus read/write scopes for every included entity type	Create a pending proposal containing up to 25 work-item, entry, or relationship changes; no project data is changed
list_proposals	projects:read	List compact proposal summaries created by the same API key in one project, with bounded pagination and an optional status filter
get_proposal	projects:read plus read scopes for included entity types	Load the exact status and before/after preview for one proposal created by the same API key
decide_proposal	projects:read plus read/write scopes for included entity types	Accept every pending change after explicit user approval, or reject the proposal without applying it
create_revert_proposal	projects:read plus read/write scopes for included entity types	Create a pending inverse proposal for an applied proposal; it does not revert data until separately approved and accepted

Review and confirmation flow

MCP changes use the same proposal and version-checking workflow as AI Agent:

1. Search for an existing work item, entry, or relationship before proposing an addition.
2. Call propose_workspace_changes. Windrunner validates the draft and returns a pending before/after preview without changing project data.
3. Use get_proposal to show the exact current preview and ask the user to accept or reject it.
4. Call decide_proposal only after the user explicitly approves that preview. ACCEPT applies all open changes; REJECT closes them without applying anything.

To undo an older accepted proposal, call create_revert_proposal. Windrunner returns a new pending inverse proposal when a safe reversal is still possible. Show that preview and use the same explicit confirmation step before accepting it. A revert can be refused when later edits make reversal unsafe.

Progressive reads

Start with a list or search tool to identify the relevant team, user, project, or work item. Candidate lists and collection tools return bounded results; collection responses include total and hasMore where pagination applies. Fetch another page only when the question requires it, then use a targeted detail tool for the selected ID.

Project summaries, attention, timelines, and workload results are aggregated on the server, so they do not require loading every underlying record into the model. This keeps MCP usage aligned with the same progressive-fetch behavior used by AI Agent. Workload results describe apparent workload rather than guaranteed availability; check their truncation flags before drawing a conclusion.

Safety

• Every proposal and applied action is attributed to the API-key owner.
• Creating or rejecting a proposal does not modify project data. Accepted changes trigger the same audit and notification behavior as equivalent human actions.
• Project-level authorization still applies: a key can only see and modify projects its owner can.
• An API key can list, inspect, decide, or revert only the MCP proposals created by that exact key.
• Windrunner rechecks project access, API-key scopes, proposal state, and target versions when applying a proposal.
• Agents should search for an existing matching work item, entry, or relationship before creating one. A clear match should be reported or updated rather than duplicated; ambiguous matches should be clarified.
• Deletes can only be expressed inside a proposal and require the same preview and explicit acceptance as other changes.