MCP Tools

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

SpecForge exposes 22 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": "queue", ... },
    { "id": "tkt_def456", "title": "Implement bcrypt hashing", "status": "queue", ... }
  ],
  "total": 4
}

search

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

{
  "query": "authentication middleware",
  "status": ["ready", "pending"],
  "priority": ["high", "critical"],
  "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 priority and complexity.

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

Returns

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

[
  {
    "id": "tkt_abc123",
    "title": "Implement JWT token generation",
    "status": "queue",
    "priority": "high",
    "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": "todo", ... },
    "blockedBy": [
      { "id": "tkt_def456", "title": "Implement bcrypt hashing", "status": "in_progress" }
    ],
    "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, planning, specifying, or validating state.

Returns

action_planning_session

Performs operations within an active planning session. This is the primary tool for building specifications — it handles 18 distinct operations.

Additional parameters depend on the operation.

Structure Operations

Linking Operations

Query & Control Operations

Example — Creating a ticket:

{
  "specificationId": "spec_xyz789",
  "operation": "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",
  "priority": "high",
  "steps": [
    "Create JwtService class in src/auth/jwt.service.ts",
    "Implement generateAccessToken method with RS256 signing",
    "Add token expiration configuration via environment variables",
    "Write unit tests for token generation and validation"
  ],
  "acceptanceCriteria": [
    "Tokens are signed with RS256 algorithm",
    "Token expiration is configurable",
    "Invalid tokens are rejected with clear error messages"
  ]
}

Returns

The response depends on the operation:

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

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

Linking operations (add_dependencies, remove_dependency, create_blueprint, etc.): Returns { id, message } or the linked entity.

Query operations (get_ticket, get_status, gps): Returns the requested data — ticket object, session status, or planning summary.

advance_phase: Returns { previousPhase, newPhase, message }.

ℹ️ The specification transitions automatically between planning, specifying, and validating states based on the operations you perform. You don’t manage these transitions 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": "in_progress",
    "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.

start_review_session

Begins an Implementation Review session for a specification.

Returns

action_review_session

Addresses findings during an active review session.

Returns

complete_review_session

Concludes the Implementation Review.

Returns

Mutations

Four tools for creating, modifying, and linking project data.

create_specification

Creates a new specification within a project.

Returns

Returns the created specification object with all fields (see get returns for Specification).

{
  "id": "spec_xyz789",
  "projectId": "proj_123",
  "title": "User Authentication System",
  "status": "draft",
  "progress": 0,
  ...
}

reopen_specification

Reopens a completed or reviewed specification for additional work.

Returns

reset_work_session

Resets completed tickets back to a workable state.

Returns

⚠️ Resetting tickets clears work session data. Linked commits and PRs are preserved, but step completions, notes, and acceptance criteria results are removed. Resetting cascades to dependent tickets.

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