MCP Tools

Complete reference for all 17 SpecForge MCP tools — parameters, usage, and examples.

SpecForge exposes 17 MCP tools organized in five categories. These tools are available to any MCP-compatible coding agent (Claude Code, Cursor, VS Code with Copilot, Gemini CLI, etc.) once the SpecForge MCP server is configured.

Queries

Six tools for reading project data, searching tickets, and generating reports. These are read-only — they never modify your specification.

get

Retrieves a single entity by type and ID.

{
  "type": "ticket",
  "id": "tkt_abc123",
  "specificationId": "spec_xyz789"
}

Returns

Returns the full entity object. The shape depends on the type parameter:

Ticket (type: "ticket"):

Specification (type: "specification"):

Epic (type: "epic"):

Project (type: "project"):

list

Lists entities of a given type with optional filters.

{
  "type": "tickets",
  "specificationId": "spec_xyz789",
  "epicId": "epic_456"
}

Returns

Returns a paginated list:

Each item in items is the full entity object (see get returns above for field details).

{
  "items": [
    { "id": "tkt_abc123", "title": "Set up User model", "status": "ready", ... },
    { "id": "tkt_def456", "title": "Implement bcrypt hashing", "status": "pending", ... }
  ],
  "total": 4
}

search

Unified search across tickets with full-text queries and structured filters.

{
  "query": "authentication middleware",
  "status": ["ready", "pending"],
  "complexity": ["large", "xlarge"],
  "limit": 10
}

Returns

Returns a paginated list of tickets:

When using the fields parameter, only the requested fields are included in each ticket object.

✅ Combine files with tags to find all tickets touching a specific part of your codebase. For example, files: ["src/auth/**"] with tags: ["security"].

get_next_actionable_tickets

Returns tickets in ready status with all dependencies satisfied, ordered by complexity.

{
  "specificationId": "spec_xyz789",
  "limit": 5
}

Returns

Returns an array of ticket objects in ready status with all dependencies satisfied, ordered by complexity (smallest first).

[
  {
    "id": "tkt_abc123",
    "title": "Implement JWT token generation",
    "status": "ready",
    "complexity": "medium",
    "epicId": "epic_456",
    "ticketNumber": 3,
    ...
  }
]

This is the primary entry point for agents deciding what to work on next. In Agent Teams, the orchestrator calls this to assign tickets to workers.

get_blocked_tickets

Returns tickets in pending status along with the reasons they’re blocked.

Returns

Returns an array of blocked ticket entries:

[
  {
    "ticket": { "id": "tkt_ghi789", "title": "Build login endpoint", "status": "pending", ... },
    "blockedBy": [
      { "id": "tkt_def456", "title": "Implement bcrypt hashing", "status": "active" }
    ],
    "daysBlocked": 2
  }
]

get_report

Generates analytical reports at different scopes and time ranges.

Returns

The response shape varies by report type:

implementation — Progress summary:

time — Time tracking:

blockers — Blocker analysis:

sessions — Active sessions (project scope only):

Errors — calling with scope !== "project" or a missing scopeId returns a validation error telling the agent to call get_report({ type: "sessions", scope: "project", scopeId: <projectId> }).

Lifecycle

Nine tools that drive specifications through planning, implementation, and review. These are the core workflow tools.

start_planning_session

Opens a planning session for a specification, enabling structural changes.

The specification must be in draft or planning state.

Returns

action_planning_session

Performs operations within an active planning session. This is the primary tool for building specifications — it handles 25 distinct operations. Each operation is passed as an operation object whose type is the operation name; the remaining fields are that operation’s payload.

To read a single ticket, use the get tool (type: "ticket") rather than a planning operation.

Specification & Structure Operations

Blueprint Operations

Step-Link Operations

Dependency Operations

Justification & Election Operations

Status Operation

Example — Creating a ticket:

{
  "specificationId": "spec_xyz789",
  "operation": {
    "type": "create_ticket",
    "epicId": "epic_456",
    "title": "Implement JWT token generation",
    "description": "Create a service that generates signed JWT access tokens with configurable expiration.",
    "complexity": "medium"
  }
}

Returns

The response depends on the operation:

Structure operations (create_epic, create_ticket, update_epic, ticket_general_actions, …): Returns the created or updated entity object.

Delete operations (delete_epic, delete_ticket, delete_blueprint): Returns { id, message } confirmation.

Linking operations (create_dependencies, link_blueprint_to_tickets, link_step_file, …): Returns { id, message } or the linked entity.

Status operation (get_planning_status): Returns the current planning session status and phase progress.

ℹ️ The specification stays in the single planning state for the whole session. The 7-phase planning machine (planning_spec → epic_decomposition → epic_expansion → ticket_decomposition → ticket_expansion → cross_validation → planned) advances on the planning session, not the specification. You don’t manage these phases manually.

complete_planning_session

Ends the planning session and triggers the Planning Review gate.

Returns

If the Planning Review gate is enabled and the specification passes, it advances to ready.

start_work_session

Begins implementation work on a specific ticket.

Transitions the ticket from ready to active.

Returns

Returns the full implementation context:

{
  "ticket": {
    "id": "tkt_abc123",
    "title": "Implement JWT token generation",
    "status": "active",
    "acceptanceCriteria": [
      { "id": "ac-0", "description": "Tokens are signed with RS256", "validated": false }
    ],
    "implementation": {
      "steps": [
        { "order": 1, "title": "Create JwtService", "action": "create", "detail": "..." }
      ]
    },
    ...
  },
  "epic": { "id": "epic_456", "title": "Token Management", ... },
  "specification": { "id": "spec_xyz789", "title": "Auth System", ... },
  "dependencies": { "blockedBy": [], "blocks": [...] },
  "relatedTickets": [...],
  "previousAttempts": [],
  "relatedDiscoveries": []
}

action_work_session

Records progress, results, and discoveries during implementation.

{
  "ticketId": "tkt_abc123",
  "steps": [
    { "index": 0, "completed": true },
    { "index": 1, "completed": true }
  ],
  "files": [
    { "path": "src/auth/jwt.service.ts", "action": "created" },
    { "path": "src/auth/jwt.service.test.ts", "action": "created" }
  ],
  "notes": "Used jose library instead of jsonwebtoken for Edge Runtime compatibility."
}

Returns

Returns confirmation with the updated work session state:

complete_work_session

Finalizes work on a ticket with a summary and validation results.

Returns

Transitions the ticket from active to done. Dependent tickets are recalculated and may become ready.

Mutations

Two tools for modifying and linking project data.

reopen_specification

Reopens a completed or reviewed specification for additional work.

Returns

link_pull_request

Associates a pull request with a completed ticket.

Returns

Returns the created link object:

Orchestration

Two tools for understanding and navigating the dependency graph.

get_critical_path

Calculates the longest dependency chain in a specification — the sequence of tickets that determines the minimum time to completion.

Returns

get_dependency_tree

Renders the complete upstream and downstream dependency tree for a specification.

Returns

Returns a tree structure showing all tickets, their dependencies, and statuses:

Useful for visualizing the overall shape of work and identifying bottlenecks.

Utility

feedback

Submit feedback, report issues, or suggest improvements.

Returns

Depends on the operation:

• submit: Returns { id, message } — the feedback ID and confirmation.
• list: Returns an array of feedback entries with id, category, summary, status, createdAt.
• get: Returns the full feedback entry by ID.

See Also

• CLI Commands — CLI equivalents for common operations
• Specification States — State machine triggered by lifecycle tools
• Ticket States — Ticket states driven by work session tools