Model Context Protocol (MCP) Setup & Reference

The Model Context Protocol (MCP) allows your AI coding assistants—including Cursor, Claude Desktop, Claude Code CLI, Cline, and Windsurf—to securely query and update your Klority workspace.

What Can Your AI Assistant Do with Klority MCP?

Inspect Stories & Backlog: Read full ticket descriptions, acceptance criteria, and subtasks.
Search Wiki PRDs: Understand architecture specs and database models before writing code.
Write & Ingest QA Tests: Pull acceptance criteria and post Playwright/Jest test execution outcomes.
Update Board Columns: Move tickets to "In Progress" or "Done" and attach AI implementation summaries.
100% Free & Open: Included on every Klority plan with zero additional seat fees.

Step 1: Generate an MCP API Token

To authenticate your local editor with Klority Cloud, generate a Personal Access Token:

Log into Klority (app.klority.com).
Navigate to Workspace Settings → Model Context Protocol (MCP).
Click Generate Dedicated Token.
Copy your token starting with klor_pat_.... You will also see your pre-filled configuration snippet ready to copy.

🔔

Keep Your Token Secret

Your Personal Access Token grants programmatic access to the projects in your workspace. Do not commit it to public repositories.

Step 2: Configure Your Client

Select your AI editor or client below to apply the configuration:

⚡ Cursor IDE Setup

Add this block to your global ~/.cursor/mcp.json or project-level .cursor/mcp.json:

{
  "mcpServers": {
    "klority": {
      "command": "npx",
      "args": ["-y", "@klority/mcp-server"],
      "env": {
        "KLORITY_API_TOKEN": "klor_pat_YOUR_TOKEN_HERE",
        "KLORITY_WORKSPACE": "your-workspace-slug",
        "KLORITY_API_URL": "https://app.klority.com/api"
      }
    }
  }
}

👉 After saving, open Cursor Settings → Features → MCP Servers. You will see klority listed with a green active indicator.

🟣 Claude Desktop Setup

Open your Claude Desktop configuration file:
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "klority": {
      "command": "npx",
      "args": ["-y", "@klority/mcp-server"],
      "env": {
        "KLORITY_API_TOKEN": "klor_pat_YOUR_TOKEN_HERE",
        "KLORITY_WORKSPACE": "your-workspace-slug"
      }
    }
  }
}

👉 Fully quit and restart Claude Desktop. The hammer/tools icon in the chat composer will now display Klority tools.

⌨️ Claude Code CLI

Run this single command in your terminal:

claude mcp add klority -e KLORITY_API_TOKEN=klor_pat_YOUR_TOKEN -e KLORITY_WORKSPACE=your-workspace-slug -- npx -y @klority/mcp-server

☁️ Hosted Remote Cloud SSE Endpoint

If your agent framework runs in the cloud (Python LangChain, LlamaIndex, or custom containers) without local Node.js:

{
  "mcpServers": {
    "klority": {
      "url": "https://app.klority.com/api/mcp/sse",
      "headers": {
        "Authorization": "Bearer klor_pat_YOUR_TOKEN",
        "x-tenant-id": "your-workspace-slug"
      }
    }
  }
}

Step 3: Available Tools Directory

Once connected, your AI assistant can execute the following tools autonomously:

Tool Name	Parameters	Description
klority_search_tasks	query, projectId, sprintId, limit	Search backlog and sprint tasks by keyword or status.
klority_get_task	taskId	Fetch full description, acceptance criteria, and comments for a task.
klority_create_task	projectId, title, description, type, priority	Create a new User Story, Bug, or Task directly in Klority.
klority_update_task_status	taskId, columnId, comment	Transition a ticket on the board and log an AI execution comment.
klority_add_task_comment	taskId, content	Post questions or implementation notes to a ticket thread.
klority_list_sprints	projectId, state	List active, future, or closed sprints and milestone dates.
klority_search_wiki	query, projectId	Semantic and keyword search across Wiki PRDs and architecture docs.
klority_get_page	pageId	Fetch Markdown content and Mermaid diagrams for a wiki document.
klority_create_or_update_page	projectId, title, content, pageId	Create or update wiki documentation (ADRs, release notes).
klority_get_qa_criteria	query, projectId	Fetch test cases and acceptance criteria to generate tests.
klority_create_test_case	projectId, title, steps, priority	Add formal test cases and assertions to the QA repository.
klority_record_test_runs	projectId, testCycleName, results	Ingest automated test results (Playwright/Jest) into Klority.
klority_search_crm	query, entity	Query client accounts, active deals, and customer feedback.

Prompt Workflows

Klority MCP also provides built-in prompt templates accessible in Claude Desktop and Cursor:

implement-story — Loads ticket requirements, pulls linked PRDs, inspects test cases, and directs the agent to produce code satisfying 100% of acceptance criteria.
generate-acceptance-tests — Generates Jest or Playwright test suites mapped directly to Klority test case format.
sprint-standup-summary — Summarizes completed, in-progress, and blocked items for daily team standups.

Troubleshooting & Health Check

You can verify that your MCP connection is working at any time:

In Klority Web, go to Settings → Model Context Protocol and click Test MCP Health.
If Cursor shows an error, ensure your token begins with klor_pat_ and that npx is available in your system PATH.
For self-hosted instances, specify KLORITY_API_URL="https://your-domain.com/api" in your client's environment variables.