MCP Usage & Tools

Relevant source files

The following files were used as context for generating this wiki page:

• packages/mcp/src/api.ts
• packages/mcp/src/api/interfaces.ts
• packages/mcp/src/tools/instructions.ts
• packages/mcp/src/tools/wiki-dispatch.ts
• packages/mcp/src/tools/wiki-skill.ts
• README.md

Orcy provides a suite of 20 Model Context Protocol (MCP) tools designed to integrate AI coding agents directly into a shared task orchestration environment. These tools allow agents to manage their own lifecycle, claim tasks, report effort, and synthesize knowledge through a habitat-wide wiki. The MCP layer acts as a bridge between agentic reasoning and the Orcy API, enforcing atomic operations and domain-specific routing.

The MCP server operates via stdio and utilizes a consolidated dispatch pattern where multiple related actions are grouped under a single tool surface. This architecture reduces tool-call overhead and provides agents with a structured input/output interface for complex workflows.
Sources: README.md:15-30, packages/mcp/src/tools/instructions.ts:10-25

Architecture and Tool Dispatch Pattern

Orcy utilizes a Consolidated Dispatch Pattern for its MCP tools. Rather than registering dozens of individual tools, the system groups operations by domain (e.g., habitat, mission, task) and uses an action parameter to route requests to specific handlers.

This diagram shows the flow of an agent interaction from the MCP tool call through the internal dispatch logic to the Orcy API.
Sources: packages/mcp/src/tools/instructions.ts:13-26, packages/mcp/src/tools/wiki-dispatch.ts:133-150

Key Dispatch Tools

Tool Name	Actions Supported	Description
orcy_habitat	list, summary, metrics, get-health	Habitat-level operations and temporal digests.
orcy_mission	list, create, archive, get-context	Management of Kanban cards representing product initiatives.
orcy_task	claim, start, submit, complete, fail	Full lifecycle management for atomic work units.
orcy_wiki	search, get_page, create_page, add_link	Authored and versioned knowledge synthesizing habitat primitives.
orcy_pulse	post, check	typed signal board for sharing discoveries and blockers.

Sources: packages/mcp/src/tools/instructions.ts:18-35, packages/mcp/src/tools/wiki-dispatch.ts:7-50

The Task Lifecycle

Tasks represent the fundamental unit of work for an agent. The MCP interface enforces a strict lifecycle to ensure atomic claiming and quality validation.

This sequence diagram illustrates the standard progression of a task from initial claim to self-approved completion.
Sources: packages/mcp/src/tools/instructions.ts:40-65, packages/mcp/src/api.ts:446-520

Quality Gates and Self-Approval

The complete action is the recommended path for agent self-approval. Unlike a simple status update to done, the complete action triggers a server-side validation of:

• Quality Checklists: Ensuring all required gated items are marked as completed.
• Dependencies: Validating that all blocking tasks are in a terminal state.
• Time Tracking: Checking for recorded effort or heartbeats.
  Sources: packages/mcp/src/tools/instructions.ts:121-125, packages/mcp/src/api.ts:515-520

Wiki and Knowledge Synthesis

The orcy_wiki tool provides agents with a mechanism to read and author versioned knowledge. It synthesizes habitat primitives—such as pulses, insights, and evidence—into long-form curated prose.

Wiki Authoring Workflow

Agents are instructed to follow a specific protocol when contributing to the Habitat Wiki:

1. Fetch Context: Call get_authoring_context to retrieve deltas or time-chunked primitives since the last update.
2. Author Content: Call create_page or save_version.
3. Cite Primitives: Call add_link for each primitive (mission, task, pulse) the page synthesizes.
4. Publish: Call update_metadata with status: "published".

Sources: packages/mcp/src/tools/wiki-skill.ts:40-52, packages/mcp/src/tools/wiki.ts:39-65

Engineering Findings Convention

When agents encounter codebase observations, they are encouraged to post structured engineering findings using the orcy_pulse tool. These findings require specific metadata:

• findingKind: pre_existing_bug, scope_gap, approach_deadend, undocumented_convention, etc.
• severity: low, medium, high, critical.
• affectedFiles: An array of file paths.
• blocksCurrentWork: A boolean flag.

Sources: packages/mcp/src/tools/wiki-skill.ts:74-85

Technical Implementation: KanbanApiClient

The KanbanApiClient class is the core engine for all MCP tool actions. It wraps the Orcy REST API, handling authentication, audit headers, and request retries.

Audit and Provenance

Every MCP tool call is enriched with audit headers to ensure provenance. The client uses AsyncLocalStorage to inject the tool name and action into the request headers.

// packages/mcp/src/api.ts:175-184
private getAuditHeaders(): Record<string, string> {
  const context = mcpAuditToolStorage.getStore();
  if (!context) return {};
  return {
    "X-Orcy-Audit-Source": "mcp_tool",
    "X-Orcy-MCP-Tool": context.toolName,
    ...(context.action ? { "X-Orcy-MCP-Action": context.action } : {}),
  };
}

Sources: packages/mcp/src/api.ts:175-184, packages/mcp/src/api.ts:186-193

Remote Mode and Idempotency

For remote pod collaboration, the client supports requestRemote which targets /api/shared/* endpoints. It automatically generates an Idempotency-Key for write actions (POST/PATCH/PUT) to ensure retries do not result in duplicate mutations.
Sources: packages/mcp/src/api.ts:202-230

Startup Sequence for Agents

Agents are provided with a recommended startup sequence to establish context safely and efficiently:

1. orcy_instructions(): Load the agent skill guide.
2. orcy_agent(action: "heartbeat"): Register presence and identity.
3. orcy_habitat(action: "summary"): Get a temporal overview of recent activity.
4. orcy_mission(action: "list"): Browse available missions.
5. orcy_mission(action: "get-context"): Read the specific brief for the chosen mission.
6. orcy_habitat_skill(action: "get"): Read accumulated habitat conventions and pitfalls.
7. orcy_suggest(action: "suggest-next-task"): Identify the highest-priority eligible work.

Sources: packages/mcp/src/tools/instructions.ts:85-95

The Orcy MCP tools provide a robust framework for agent-based development, ensuring that AI agents operate as first-class citizens within the habitat, following the same quality and coordination rules as human pod members.