MCP API

The Katatan MCP API is an interface that lets AI agents manage test operations via the Model Context Protocol (MCP).

Endpoint: https://mcp.katatan.com/mcp (HTTP transport)

All communication goes through MCP protocol tools/call requests. Pass the authorization token as an HTTP transport header — you do not need to include it in tool arguments.

Authentication

HTTP transport (recommended)

Set your MCP access token in the Authorization: Bearer header.

Copy{
  "mcpServers": {
    "katatan": {
      "type": "http",
      "url": "https://api.katatan.com/mcp",
      "headers": {
        "Authorization": "Bearer kat_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

stdio transport (local development)

Set your access token in the KATATAN_TOKEN environment variable.

Copy{
  "mcpServers": {
    "katatan": {
      "type": "stdio",
      "command": "node",
      "args": ["dist/src/scripts/local-mcp.js"],
      "env": {
        "DATABASE_URL": "postgresql://...",
        "KATATAN_TOKEN": "kat_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Rate Limits

When the limit is exceeded the error code RATE_LIMIT_EXCEEDED is returned.

Common Parameters

author parameter (optional, all tools)

All tools accept an author parameter. It is recorded in Audit logs and in the createdBy/updatedBy fields of data. If omitted, the UUID of the access token is used.

Copyauthor: string (max 100 characters, optional)

Composite ID format

Error Specification

When a tool call fails, the MCP response sets isError: true and content[0].text contains the following JSON.

Copy{
  "error": {
    "code": "ERROR_CODE",
    "message": "Error message",
    "details": {}
  }
}

Common Response Types

TestSpec object

Copy{
  id: string                    // UUID
  projectId: string
  name: string
  description: string | null
  webhookId: string | null
  webhook: {
    url: string
    headers: Record<string, string> | null
  } | null
  requiredTesterEnv: string | null
  requiredProductEnv: string | null
  testCaseCount?: number        // included in list responses only
  labels?: Label[]              // included in list responses only
  createdBy: string | null
  updatedBy: string | null
  createdAt: string             // ISO 8601
  updatedAt: string             // ISO 8601
}

TestCase object

Copy{
  id: string                    // UUID (internal ID)
  specId: string                // parent spec UUID
  index: number                 // display order (changes on reorder/delete)
  caseNumber: number            // stable ID (UI label: "case-{caseNumber}")
  labels: Label[]
  testSubject: string
  preconditions: string | null
  steps: string[]
  expectedResult: string
  notes: string | null
  createdBy: string | null
  updatedBy: string | null
  createdAt: string             // ISO 8601
  updatedAt: string             // ISO 8601
}

TestReport object

Copy{
  id: string                    // UUID
  specId: string                // source spec UUID
  name: string
  notes: string | null
  status: "NOT_STARTED" | "IN_PROGRESS" | "COMPLETED" | "ABORTED"
  webhookEnabled: boolean
  startedAt: string             // ISO 8601
  completedAt: string | null    // first completion timestamp
  lastCompletedAt: string | null
  createdBy: string | null
  updatedBy: string | null
  createdAt: string             // ISO 8601
  updatedAt: string             // ISO 8601
  reportResults?: TestReportResult[]  // included in get_test_report only
}

TestReportResult object

Copy{
  id: string                    // UUID
  reportId: string
  testCaseId: string
  testResult: "OK" | "NG" | "SKIP" | null
  tester: string | null
  notes: string | null
  executionResultLink: string | null
  resultRecordedAt: string | null
  createdAt: string             // ISO 8601
  updatedAt: string             // ISO 8601
  // Snapshot columns (test case state at report creation time)
  snapshotCaseNumber: number | null
  snapshotTestSubject: string | null
  snapshotPreconditions: string | null
  snapshotSteps: string[] | null
  snapshotExpectedResult: string | null
  snapshotLabels: { id: string; name: string; color: string }[] | null
  snapshotNotes: string | null
}

Label object

Copy{
  id: string
  workspaceId: string
  name: string
  color: "gray" | "red" | "orange" | "yellow" | "green" | "blue" | "purple" | "pink"
  createdBy: string | null
  updatedBy: string | null
  createdAt: string             // ISO 8601
  updatedAt: string             // ISO 8601
}

DictionaryEntry object

Copy{
  id: string
  projectId: string
  key: string
  value: string
  description: string | null
  createdBy: string | null
  updatedBy: string | null
  createdAt: string             // ISO 8601
  updatedAt: string             // ISO 8601
}

Tool List