MCP Servers

ticket-rs provides two MCP (Model Context Protocol) servers for AI assistants:

Server	Purpose	Use Case
ticket-docs	Search tk documentation	Help AI understand tk commands and features
ticket-mcp	Full issue management tools	Let AI agents create, update, and manage issues

`ticket-docs` (Docs MCP)

The docs MCP server gives AI assistants access to search ticket-rs documentation directly.

Setup

Claude Code
Cursor
Windsurf
Manual

Add to project .mcp.json:

claude mcp add --transport http --scope project ticket-docs https://docs.ticket.rs/mcp

Add --scope user to make it available across all projects.

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "ticket-docs": {
      "url": "https://docs.ticket.rs/mcp"
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "ticket-docs": {
      "serverUrl": "https://docs.ticket.rs/mcp"
    }
  }
}

Add to your .mcp.json:

{
  "mcpServers": {
    "ticket-docs": {
      "type": "http",
      "url": "https://docs.ticket.rs/mcp"
    }
  }
}

Available Tools

Tool	Description
`search_docs`	Search tk documentation for relevant content

Example prompts:

“How do I add a dependency between issues?”
“What does tk triage show?”
“How do I sync with GitHub?”

`ticket-mcp` (Agentic Tools)

The ticket-mcp package provides full issue management capabilities, allowing AI agents to create, update, and manage issues directly.

Installation

# Recommended: use uv
uv tool install ticket-mcp

# Or with pip
pip install ticket-mcp

Requires Python 3.10+ and the tk binary in PATH. Install tk first: curl -fsSL https://ticket-rs.io/install.sh | bash

Setup

Claude Code
Cursor
Manual

claude mcp add ticket uvx ticket-mcp

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "ticket": {
      "command": "uvx",
      "args": ["ticket-mcp"]
    }
  }
}

Add to your .mcp.json:

{
  "mcpServers": {
    "ticket": {
      "command": "uvx",
      "args": ["ticket-mcp"]
    }
  }
}

Available Tools

Read Operations

Tool	Description
`ready`	Get issues ready to work on (no blocking dependencies)
`list_issues`	List issues with optional filters
`show`	Show full details for a specific issue
`stats`	Get repository statistics
`search`	Search issues using TF-IDF similarity
`similar`	Find issues similar to a given issue

Write Operations

Tool	Description
`create`	Create a new issue
`update`	Update an existing issue
`close`	Close an issue
`launch`	Mark an issue as in-progress
`resolve`	Resolve an issue (close + show unblocked)

Dependency Operations

Tool	Description
`dep_add`	Add a dependency between issues
`dep_remove`	Remove a dependency between issues
`dep_tree`	Show dependency tree for an issue
`dep_cycles`	Detect dependency cycles in the graph

AI/Analytics Operations

Tool	Description
`triage`	THE MEGA-COMMAND: unified recommendations, quick wins, blockers, health
`next_action`	Get single top recommendation for next action
`priority`	Get PageRank-based priority recommendations
`plan`	Get parallel execution plan (topological sort)
`insights`	Get graph analytics (PageRank, betweenness, critical path)

Workflow Operations

Tool	Description
`prime`	Get AI workflow context for the repository
`validate`	Validate all issue files
`context`	Set or show workspace context

Discovery Tools

Tool	Description
`discover_tools`	List all available tools (saves context)
`get_tool_info`	Get detailed info for a specific tool

Usage Example

# 1. Set workspace context
context(workspace_root='/path/to/repo', action='set')

# 2. Get AI recommendations
triage()  # Full recommendations with health score
# or
next_action()  # Single top pick for quick decisions

# 3. See what's ready to work on
ready()

# 4. Start work on an issue
launch('tk-123')

# 5. Resolve when done (shows newly unblocked issues)
resolve('tk-123')

Context Engineering

ticket-mcp is optimized for AI agent efficiency:

Lazy tool loading: Use discover_tools() first, then get_tool_info() for details
Minimal models: List views use ~80% less tokens than full issues
Result compaction: Large result sets are automatically compacted

Configure thresholds via environment variables:

TICKET_MCP_COMPACTION_THRESHOLD=20  # Compact results with more than N issues
TICKET_MCP_PREVIEW_COUNT=5          # Show first N issues in preview

Which Should I Use?

Docs MCP

Best for learningUse when you want AI to understand tk commands and answer questions about features.

ticket-mcp

Best for automationUse when you want AI agents to actually manage your issues—create, update, close, etc.

Recommendation: Use both together. The docs server helps AI understand how to use tk, while ticket-mcp lets it take action.

Troubleshooting

MCP server not found

Verify the server is configured:

# For Claude Code
claude mcp list

You should see ticket-docs and/or ticket-mcp in the list.

ticket-mcp: tk binary not found

Install the tk binary first:

curl -fsSL https://ticket-rs.io/install.sh | bash

Verify it’s in your PATH:

which tk
tk --version

ticket-mcp: No issues found

Make sure you’ve set the workspace context and initialized tickets:

# In your project directory
tk init
tk demo  # Create sample issues to test

Connection errors (docs MCP)

The docs MCP server requires internet access to reach docs.ticket.rs. Check your network connection.

Getting Started

CLI Reference

Integrations

`ticket-docs` (Docs MCP)

Setup

Available Tools

`ticket-mcp` (Agentic Tools)

Installation

Setup

Available Tools

Read Operations

Write Operations

Dependency Operations

AI/Analytics Operations

Workflow Operations

Discovery Tools

Usage Example

Context Engineering

Which Should I Use?

Docs MCP

ticket-mcp

Troubleshooting

Next Steps

Claude Code Setup

CLI Commands

Getting Started

CLI Reference

Integrations

​ticket-docs (Docs MCP)

​Setup

​Available Tools

​ticket-mcp (Agentic Tools)

​Installation

​Setup

​Available Tools

​Read Operations

​Write Operations

​Dependency Operations

​AI/Analytics Operations

​Workflow Operations

​Discovery Tools

​Usage Example

​Context Engineering

​Which Should I Use?

Docs MCP

ticket-mcp

​Troubleshooting

​Next Steps

Claude Code Setup

CLI Commands

`ticket-docs` (Docs MCP)

Setup

Available Tools

`ticket-mcp` (Agentic Tools)

Installation

Setup

Available Tools

Read Operations

Write Operations

Dependency Operations

AI/Analytics Operations

Workflow Operations

Discovery Tools

Usage Example

Context Engineering

Which Should I Use?

Troubleshooting

Next Steps