Agent Quickstart

This guide gets an AI agent filing real bugs in Hackorda in under 5 minutes. Covers Claude Desktop setup; other MCP hosts follow the same pattern.

Status: this guide describes the target state. The MCP server ships in roadmap Phase 1B. Until then, use the REST API directly with an API key.

Step 1: Create an API key

Go to https://hackorda.kz/app/admin/integrations (admin access required).
Click API Keys → New key.
Name it (e.g. "Claude Desktop — dev").
Select scopes:
- cycles:read — to list and read cycles
- issues:write — to file bugs
- runs:write — to start/end runs (optional for basic filing)
Optionally restrict to specific cycle IDs.
Copy the key — it starts hk_live_... and is shown only once.

Step 2: Install the MCP server

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "hackorda": {
      "command": "npx",
      "args": ["-y", "@hackorda/mcp-server"],
      "env": {
        "HACKORDA_API_KEY": "hk_live_your_key_here",
        "HACKORDA_BASE_URL": "https://hackorda.kz"
      }
    }
  }
}

Restart Claude Desktop. You'll see "hackorda" in the MCP connections panel.

Cursor

Same config in .cursor/mcp.json in your project root.

Custom agent (Node.js)

npm install @hackorda/mcp-server

import { HackordaMcpServer } from '@hackorda/mcp-server';

const server = new HackordaMcpServer({
  apiKey: process.env.HACKORDA_API_KEY,
  baseUrl: 'https://hackorda.kz',
});

server.connect(transport);

Step 3: Talk to Hackorda through your agent

Try these prompts in Claude Desktop:

"What test cycles are currently active?"
→ calls list_cycles(status='active')

"Show me the open bugs in the Attikka v0.8 cycle"
→ calls list_issues(cycleId='...', status='open')

"File a bug: the login button is missing on mobile at /sign-in"
→ calls file_issue(cycleId, { title, description, severity: 'medium' })

"What's my current payout balance?"
→ calls get_balance()

What's next

CI integration guide — auto-file bugs from test failures
API key scopes reference — fine-grained permissions
Agent platform & MCP tools — every tool with inputs/outputs