1443 words · 7 min read

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.

Prefer a CLI? If loading MCP tool schemas into your agent's context isn't ideal — for CI/CD pipelines, scripts, or context-conscious coding agents — see the KATATAN CLI, a thin client that talks to this same /mcp endpoint using the same tokens, permissions, and rate limits. It's available on every plan.

Authentication

HTTP transport (recommended)

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

{
  "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.

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

Rate Limits

Scope	Limit	Window
Per project (free plan)	100 calls	1 hour
Per project (paid plan)	Plan-dependent	1 hour

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.

author: string (max 100 characters, optional)

Composite ID format

Field	Format	Example
Test spec composite ID	`{projectId}.{specUuid}`	`proj-abc.550e8400-e29b-41d4-a716-446655440000`
Test report composite ID	`{projectId}.{specUuid}.{reportUuid}`	`proj-abc.550e8400....7f000001`

Error Specification

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

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

Code	Cause	Condition
`AUTHENTICATION_ERROR`	Authentication failure	Token missing, invalid, or expired
`AUTHORIZATION_ERROR`	Authorization failure	Token lacks permission for the tool, or project is inaccessible
`VALIDATION_ERROR`	Invalid input	Missing required parameter, type mismatch, string too long, etc.
`NOT_FOUND`	Resource not found	Resource with the specified ID does not exist
`CONFLICT`	Conflict	An entry with the same key already exists (Dictionary, etc.)
`RATE_LIMIT_EXCEEDED`	Rate limit exceeded	Hourly call limit has been reached
`QUOTA_EXCEEDED`	Plan quota exceeded	Resource count limit for the plan has been reached
`FEATURE_NOT_AVAILABLE`	Feature unavailable	Feature is not available on the current plan
`INTERNAL_ERROR`	Internal server error	Unexpected error

Common Response Types

TestSpec object

{
  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

{
  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

{
  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

{
  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

{
  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

{
  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

Tool	Description	Permission	Mode
`list_test_specs`	List test specs	All users	Sync
`get_test_spec`	Get test spec detail	All users	Sync
`create_test_spec`	Create test spec	Owner/Editor	Sync
`update_test_spec`	Update test spec	Owner/Editor	Sync
`delete_test_spec`	Delete test spec (fails if reports exist)	Owner/Editor	Sync
`list_test_cases_by_spec`	List test cases under a spec	All users	Sync
`list_test_cases`	List all test cases	All users	Sync
`get_test_case`	Get test case detail	All users	Sync
`create_test_case`	Create test case	Owner/Editor	Sync
`batch_create_test_cases`	Batch create test cases (max 1000)	Owner/Editor	Sync
`update_test_case`	Update test case	Owner/Editor	Sync
`delete_test_case`	Delete test case	Owner/Editor	Sync
`batch_delete_test_cases`	Batch delete test cases (max 100)	Owner/Editor	Sync
`start_test`	Start test (create report)	Owner/Editor	Sync
`list_test_reports`	List test reports	All users	Sync
`get_test_report`	Get test report detail	All users	Sync
`update_test_report_result`	Update single test result	Owner/Editor	Async (queue)
`batch_update_test_results`	Batch update test results (max 100)	Owner/Editor	Sync
`abort_test_report`	Abort report	Owner/Editor	Sync
`reopen_test_report`	Reopen report	Owner/Editor	Sync
`force_complete_test_report`	Force complete report	Owner/Editor	Sync
`delete_test_report`	Delete report (cascades to test results)	Owner/Editor	Sync
`get_completion_summary`	Get completion rate summary	All users	Sync
`create_label`	Create label	Owner/Editor	Sync
`list_labels`	List labels	All users	Sync
`assign_labels_to_test_case`	Assign labels to test case	Owner/Editor	Sync
`delete_label`	Delete label	Owner/Editor	Sync
`create_dictionary_entry`	Create dictionary entry	Owner/Editor	Sync
`list_dictionary_entries`	List dictionary entries	All users	Sync
`get_dictionary_entry`	Get dictionary entry	All users	Sync
`update_dictionary_entry`	Update dictionary entry	Owner/Editor	Sync
`delete_dictionary_entry`	Delete dictionary entry (not cascaded)	Owner/Editor	Sync
`upload_test_case_image`	Attach image to test case	Owner/Editor	Sync
`delete_test_case_image`	Delete test case image	Owner/Editor	Sync
`list_vulnerability_targets`	List vulnerability scan target URLs	All users	Sync
`list_vulnerability_reports`	List vulnerability scan reports	All users	Sync
`get_vulnerability_report`	Get vulnerability scan report detail	All users	Sync

Deleting Resources

Seven tools support deletion: delete_test_spec, delete_test_case, batch_delete_test_cases, delete_test_report, delete_label, delete_dictionary_entry, and delete_test_case_image. All deletions are permanent and cannot be undone, and every call is recorded in the audit log.

Delete tools are not automatically enabled on tokens created before this feature shipped. Newly created tokens have every tool enabled by default — see Create MCP access token to enable delete tools on an existing token.

Run tests

Test Spec Tools