MCP (Model Context Protocol)

The Kayse AI MCP server enables AI assistants to interact with your Kayse AI data through the Model Context Protocol.

Overview

MCP allows AI assistants (like Claude Desktop, Cline, Cursor, and others) to:

• Read and update operational data across cases, clients, case lists, forms, campaigns, calls, tasks, and notes
• Review company configuration data such as case types, case statuses, webhooks, admins, and audit logs
• Trigger selected workflow actions such as sending case SMS/email messages, testing webhooks, replaying webhook deliveries, and reordering case statuses
• Search and filter your data using natural language in any MCP-compatible client

Authentication

MCP uses Bearer token authentication with the same API keys as the Kayse AI Public API. Include your API key as a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

See Authentication for details on generating and managing API keys.

Endpoint

POST https://public-api.kayse.ai/v1/mcp

All MCP operations use this single endpoint. The specific tool to invoke is specified in the JSON-RPC request body.

How Calls Work

MCP uses JSON-RPC over a single HTTP endpoint.

• Use tools/list to discover the current tool catalog
• Use tools/call with a tool name and arguments object to execute a tool

Discover Tools

Call tools/list to get the full schema for every available tool, including argument names, types, and descriptions.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

Call a Tool

Call tools/call with the tool name and an arguments object. The response contains the tool result as a JSON text block.

Request

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "list_cases",
    "arguments": {
      "page": 1,
      "per_page": 25
    }
  }
}

Pagination

List tools that support pagination accept page (1-based, defaults to 1) and per_page (defaults to 25) arguments. Paginated responses include:

Field	Type	Description
current_page	Integer	The current page number
total_pages	Integer	Total number of pages
total_records	Integer	Total number of records matching the query

These fields are returned alongside the resource array (e.g. cases, clients).

INFO

list_audit_logs uses a slightly different pagination envelope with total, page, and page_size fields.

Some list tools are not paginated and return a single object with an items array (for example list_webhooks, list_webhook_logs, list_case_type_custom_fields, and list_hierarchical_case_statuses). Read the result list from the items field.

---

Cases

list_cases

List cases for the company. Supports pagination and keyword search.

Arguments

Field	Required	Type	Description
page	false	Integer	Page number (1-based). Defaults to 1
per_page	false	Integer	Items per page. Defaults to 25
key	false	String	Search keyword to filter cases by name or case number

Response Fields

Field	Type	Description
id	Integer	Case ID
name	String	Case name
case_number	String	External case number
description	String	Case description
type	String	Case type name
status	String	Case status name
court_name	String	Court name
jurisdiction	String	Jurisdiction
representative	String	Representative
external_source	String	External source identifier
external_source_id	String	External source record ID
is_obo	Boolean	Whether the case is on behalf of

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_cases",
    "arguments": {
      "page": 1,
      "per_page": 10,
      "key": "smith"
    }
  }
}

Response

{
  "current_page": 1,
  "total_pages": 3,
  "total_records": 28,
  "cases": [
    {
      "id": 42,
      "name": "Smith v. Johnson",
      "case_number": "CV-2025-001",
      "type": "Personal Injury",
      "status": "Active",
      "is_obo": false
    }
  ]
}

get_case

Get a single case by ID.

Arguments

Field	Required	Type	Description
id	true	Integer	The case ID

Returns the same fields as list_cases for a single case.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_case",
    "arguments": { "id": 42 }
  }
}

create_case

Create a new case. Type and status are created automatically if they don't exist.

Arguments

Field	Required	Type	Description
type	true	String	Case type name. Created if it does not exist
status	true	String	Case status name. Created if it does not exist
name	false	String	Case name. Auto-generated if omitted
case_number	false	String	External case number
description	false	String	Case description
court_name	false	String	Court name
jurisdiction	false	String	Jurisdiction
representative	false	String	Representative
external_source	false	String	External source identifier
external_source_id	false	String	External source record ID

Returns the created case object.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_case",
    "arguments": {
      "name": "Smith v. Johnson",
      "type": "Personal Injury",
      "status": "New",
      "case_number": "CV-2025-001"
    }
  }
}

update_case

Update an existing case. Only provided fields are updated.

Arguments

Field	Required	Type	Description
id	true	Integer	The case ID to update
name	false	String	New case name
case_number	false	String	New case number
type	false	String	Case type name
status	false	String	Case status name
description	false	String	New description
court_name	false	String	New court name
jurisdiction	false	String	New jurisdiction
representative	false	String	New representative
external_source	false	String	External source identifier
external_source_id	false	String	External source record ID

Returns the updated case object.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_case",
    "arguments": {
      "id": 42,
      "status": "In Review"
    }
  }
}

send_sms_to_case

Send an SMS message to all clients linked to a case.

Arguments

Field	Required	Type	Description
case_id	true	Integer	The case ID to send SMS to
message	true	String	The SMS message body
send_chat_message	false	Boolean	Also record as a chat message. Defaults to false

Response

{ "status": "sms scheduled" }

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "send_sms_to_case",
    "arguments": {
      "case_id": 42,
      "message": "Your case has been updated."
    }
  }
}

send_email_to_case

Send an email to all clients linked to a case.

Arguments

Field	Required	Type	Description
case_id	true	Integer	The case ID to send email to
subject	true	String	The email subject
message	true	String	The email body
send_chat_message	false	Boolean	Also record as a chat message. Defaults to false

Response

{ "status": "email scheduled" }

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "send_email_to_case",
    "arguments": {
      "case_id": 42,
      "subject": "Case Update",
      "message": "Your case status has been changed to In Review."
    }
  }
}

---

Contacts

list_clients

List clients for the company. Supports pagination and keyword search.

Arguments

Field	Required	Type	Description
page	false	Integer	Page number (1-based). Defaults to 1
per_page	false	Integer	Items per page. Defaults to 25
key	false	String	Search keyword to filter clients by name or email

Response Fields

Field	Type	Description
id	Integer	Client ID
first_name	String	Client first name
last_name	String	Client last name
email	String	Email address
mobile	String	Mobile phone number
gender	String	Gender
city	String	City name
state	String	State code
postal_code	String	Postal/ZIP code
address_line1	String	Primary address line
address_line2	String	Secondary address line
external_source	String	External source identifier
external_source_id	String	External source record ID

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_clients",
    "arguments": {
      "page": 1,
      "per_page": 10,
      "key": "doe"
    }
  }
}

Response

{
  "current_page": 1,
  "total_pages": 1,
  "total_records": 2,
  "clients": [
    {
      "id": 101,
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "mobile": "+1234567890",
      "city": "New York",
      "state": "NY"
    }
  ]
}

get_client

Get a single client by ID.

Arguments

Field	Required	Type	Description
id	true	Integer	The client ID

Returns the same fields as list_clients for a single client.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_client",
    "arguments": { "id": 101 }
  }
}

create_client

Create a new client.

Arguments

Field	Required	Type	Description
first_name	true	String	Client first name
last_name	true	String	Client last name
email	false	String	Email address
mobile	false	String	Mobile phone number
gender	false	String	Gender
city	false	String	City name. Must be paired with state
state	false	String	State code. Must be paired with city
postal_code	false	String	Postal/ZIP code
address_line1	false	String	Primary address line
address_line2	false	String	Secondary address line
external_source	false	String	External source identifier
external_source_id	false	String	External source record ID

Returns the created client object.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_client",
    "arguments": {
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane.doe@example.com",
      "city": "Los Angeles",
      "state": "CA"
    }
  }
}

update_client

Update an existing client. Only provided fields are updated.

Arguments

Field	Required	Type	Description
id	true	Integer	The client ID to update
first_name	false	String	New first name
last_name	false	String	New last name
email	false	String	New email address
mobile	false	String	New mobile phone number
gender	false	String	New gender
city	false	String	City name. Must be paired with state
state	false	String	State code. Must be paired with city
postal_code	false	String	New postal/ZIP code
address_line1	false	String	New primary address line
address_line2	false	String	New secondary address line
external_source	false	String	New external source identifier
external_source_id	false	String	New external source record ID

Returns the updated client object.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_client",
    "arguments": {
      "id": 101,
      "email": "jane.updated@example.com"
    }
  }
}

---

Case Lists

list_case_lists

List case lists for the company. Supports pagination and search.

Arguments

Field	Required	Type	Description
page	false	Integer	Page number (1-based). Defaults to 1
per_page	false	Integer	Items per page. Defaults to 25
key	false	String	Search keyword to filter case lists by name
case_type_id	false	Integer	Filter by case type ID

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_case_lists",
    "arguments": { "per_page": 10 }
  }
}

get_case_list

Get a single case list by ID.

Arguments

Field	Required	Type	Description
id	true	Integer	The case list ID

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_case_list",
    "arguments": { "id": 5 }
  }
}

create_case_list

Create a new case list.

Arguments

Field	Required	Type	Description
name	true	String	Name of the case list
description	false	String	Description of the case list
case_type_id	false	Integer	Restrict to a specific case type ID

Returns the created case list object.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_case_list",
    "arguments": {
      "name": "Active PI Cases",
      "description": "All active personal injury cases"
    }
  }
}

update_case_list

Update an existing case list.

Arguments

Field	Required	Type	Description
id	true	Integer	The case list ID to update
name	false	String	New name
description	false	String	New description
case_type_id	false	Integer	New case type ID

Returns the updated case list object.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_case_list",
    "arguments": {
      "id": 5,
      "name": "Active PI Cases - Q2"
    }
  }
}

---

Forms

list_forms

List forms for the company. Supports pagination and keyword search.

Arguments

Field	Required	Type	Description
page	false	Integer	Page number (1-based). Defaults to 1
per_page	false	Integer	Items per page. Defaults to 25
key	false	String	Search keyword to filter forms by name

Response Fields

Field	Type	Description
id	Integer	Form ID
name	String	Form name
description	String	Form description
due_in	Integer	Due-in period (days)
case_type_id	Integer	Associated case type ID
version	Integer	Form version number

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_forms",
    "arguments": { "key": "intake" }
  }
}

get_form

Get a single form by ID.

Arguments

Field	Required	Type	Description
id	true	Integer	The form ID

Returns the same fields as list_forms for a single form.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_form",
    "arguments": { "id": 8 }
  }
}

---

Campaigns

list_campaigns

List campaigns for the company. Supports pagination and keyword search.

Arguments

Field	Required	Type	Description
page	false	Integer	Page number (1-based). Defaults to 1
per_page	false	Integer	Items per page. Defaults to 25
key	false	String	Search keyword to filter campaigns by name

Response Fields

Field	Type	Description
id	Integer	Campaign ID
name	String	Campaign name
status	String	Campaign status
case_list_id	Integer	Associated case list ID
case_list_name	String	Associated case list name
is_obo	Boolean	Whether the campaign is on behalf of
never_ending	Boolean	Whether the campaign is recurring
is_public	Boolean	Whether the campaign is public
run_count	Integer	Number of campaign runs

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_campaigns",
    "arguments": { "per_page": 5 }
  }
}

Response

{
  "current_page": 1,
  "total_pages": 2,
  "total_records": 8,
  "campaigns": [
    {
      "id": 15,
      "name": "Q2 Follow-up",
      "status": "active",
      "case_list_id": 5,
      "case_list_name": "Active PI Cases",
      "is_obo": false,
      "never_ending": false,
      "is_public": true,
      "run_count": 3
    }
  ]
}

get_campaign

Get a single campaign by ID.

Arguments

Field	Required	Type	Description
id	true	Integer	The campaign ID

Returns the same fields as list_campaigns for a single campaign.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_campaign",
    "arguments": { "id": 15 }
  }
}

---

Calls

list_calls

List calls for the company. Supports pagination, keyword search, and filtering by campaign or case.

Arguments

Field	Required	Type	Description
page	false	Integer	Page number (1-based). Defaults to 1
per_page	false	Integer	Items per page. Defaults to 25
campaign_id	false	Integer	Filter by campaign ID
case_id	false	Integer	Filter by case ID
key	false	String	Search keyword to filter calls

Response Fields (list)

Field	Type	Description
id	Integer	Call ID
start_time	String	Call start time (ISO 8601)
duration	String	Call duration
sentiment_score	Number	Sentiment score
client_name	String	Client name
result	String	Call result
campaign_name	String	Campaign name
campaign_id	Integer	Campaign ID
case_name	String	Case name
case_id	String	Case ID
opted_out	Boolean	Whether client opted out
is_disqualified	Boolean	Whether client was disqualified
disconnection_reason	String	Disconnection reason
end_reason	String	End reason
direction	String	Call direction
agent_name	String	Voice agent name

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_calls",
    "arguments": {
      "campaign_id": 15,
      "per_page": 10
    }
  }
}

get_call

Get a single call by ID with transcript and summary details.

Arguments

Field	Required	Type	Description
id	true	Integer	The call ID

Additional Response Fields (detail)

The detail response includes all list fields plus:

Field	Type	Description
client_id	Integer	Client ID
client_phone	String	Client phone number
summary	String	AI-generated call summary

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_call",
    "arguments": { "id": 200 }
  }
}

---

Tasks

list_tasks

List reusable task definitions for the company. Supports pagination and search.

Arguments

Field	Required	Type	Description
page	false	Integer	Page number (1-based). Defaults to 1
per_page	false	Integer	Items per page. Defaults to 25
key	false	String	Search keyword to filter tasks by title

Response Fields

Field	Type	Description
id	Integer	Task ID
title	String	Task title
body	String	Task body/description
response_type	String	Response type
todo_count	Integer	Number of pending instances
completed_count	Integer	Number of completed instances
overdue_count	Integer	Number of overdue instances
skipped_count	Integer	Number of skipped instances

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_tasks",
    "arguments": { "key": "follow" }
  }
}

get_task

Get a single task by ID with its case task instances.

Arguments

Field	Required	Type	Description
id	true	Integer	The task ID

Response Fields

Field	Type	Description
id	Integer	Task ID
title	String	Task title
body	String	Task body/description
response_type	String	Response type
case_tasks	Array	Case task instances
case_tasks[].id	Integer	Case task ID
case_tasks[].case_id	Integer	Associated case ID
case_tasks[].status	String	Case task status

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_task",
    "arguments": { "id": 10 }
  }
}

Response

{
  "id": 10,
  "title": "Follow-up Call",
  "body": "Complete follow-up call with client",
  "response_type": "boolean",
  "case_tasks": [
    { "id": 50, "case_id": 42, "status": "completed" },
    { "id": 51, "case_id": 43, "status": "todo" }
  ]
}

---

Notes

list_notes

List notes for a case or client. Either case_id or client_id is required.

Arguments

Field	Required	Type	Description
page	false	Integer	Page number (1-based). Defaults to 1
per_page	false	Integer	Items per page. Defaults to 25
case_id	conditional	Integer	Filter notes by case ID
client_id	conditional	Integer	Filter notes by client ID
search	false	String	Search keyword to filter notes

WARNING

Either case_id or client_id must be provided.

Response Fields

Field	Type	Description
id	Integer	Note ID
ulid	String	Note ULID
title	String	Note title
body	String	Note body
type	String	Note type (case or client)
reference_id	Integer	Associated case or client ID
case_name	String	Case name (if type is case)
author_name	String	Note author name
created_at	String	Creation timestamp (ISO 8601)

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_notes",
    "arguments": {
      "case_id": 42,
      "per_page": 10
    }
  }
}

create_note

Create a note for a case or client.

Arguments

Field	Required	Type	Description
body	true	String	The note body
type	true	String	The note type: case or client
reference_id	true	Integer	The referenced case or client ID
title	false	String	Optional note title
attachment_ulids	false	Array	Optional attachment ULIDs to associate

Response

{ "note_id": 123, "status": "created" }

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_note",
    "arguments": {
      "title": "Client meeting notes",
      "body": "Discussed case timeline and next steps.",
      "type": "case",
      "reference_id": 42
    }
  }
}

update_note

Update an existing note by ULID. At least one of title, body, or attachment_ids must be provided.

Arguments

Field	Required	Type	Description
ulid	true	String	The note ULID
title	false	String	Replacement title
body	false	String	Replacement note body (cannot be empty)
attachment_ids	false	Array	Replacement attachment ULIDs

Returns the updated note object.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_note",
    "arguments": {
      "ulid": "01J5A3B4C5D6E7F8G9H0",
      "body": "Updated meeting notes with action items."
    }
  }
}

---

Case Types

list_case_types

List case types for the company. Supports pagination and search by name.

Arguments

Field	Required	Type	Description
page	false	Integer	Page number (1-based). Defaults to 1
per_page	false	Integer	Items per page. Defaults to 25
name	false	String	Filter case types by name

Response Fields

Field	Type	Description
id	Integer	Case type ID
name	String	Case type name
description	String	Case type description
pronunciation	String	Pronunciation hint
number_of_cases	Integer	Number of associated cases

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_case_types",
    "arguments": {}
  }
}

get_case_type

Get a single case type by ID.

Arguments

Field	Required	Type	Description
id	true	Integer	The case type ID

Returns the same fields as list_case_types for a single case type.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_case_type",
    "arguments": { "id": 3 }
  }
}

create_case_type

Create a new case type.

Arguments

Field	Required	Type	Description
name	true	String	Case type name
description	false	String	Case type description
pronunciation	false	String	Optional pronunciation hint

Returns the created case type object.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_case_type",
    "arguments": {
      "name": "Workers Compensation",
      "pronunciation": "workers comp"
    }
  }
}

update_case_type

Update an existing case type.

Arguments

Field	Required	Type	Description
id	true	Integer	The case type ID to update
name	false	String	New case type name
description	false	String	New case type description
pronunciation	false	String	New pronunciation hint

Returns the updated case type object.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_case_type",
    "arguments": {
      "id": 3,
      "description": "Workers' compensation injury cases"
    }
  }
}

list_case_type_custom_fields

List custom fields for a case type.

Arguments

Field	Required	Type	Description
id	true	Integer	The case type ID

Response

Returns an object with an items array of custom field objects (same shape as create_case_type_custom_field).

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_case_type_custom_fields",
    "arguments": { "id": 3 }
  }
}

Response

{
  "items": [
    {
      "id": 101,
      "key": "accident_date",
      "source": "manual",
      "created_at": "2025-06-15T14:30:00Z"
    }
  ]
}

create_case_type_custom_field

Create a manual custom field for a case type.

Arguments

Field	Required	Type	Description
id	true	Integer	The case type ID
key	true	String	The custom field key

Returns the created custom field object.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_case_type_custom_field",
    "arguments": {
      "id": 3,
      "key": "accident_date"
    }
  }
}

---

Case Statuses

list_case_statuses

List case statuses for the company. Supports pagination and search by name.

Arguments

Field	Required	Type	Description
page	false	Integer	Page number (1-based). Defaults to 1
per_page	false	Integer	Items per page. Defaults to 25
name	false	String	Filter case statuses by name

Response Fields

Field	Type	Description
id	Integer	Case status ID
name	String	Case status name
description	String	Case status description
priority	Integer	Display priority
number_of_cases	Integer	Number of associated cases

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_case_statuses",
    "arguments": {}
  }
}

get_case_status

Get a single case status by ID.

Arguments

Field	Required	Type	Description
id	true	Integer	The case status ID

Returns the same fields as list_case_statuses for a single case status.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_case_status",
    "arguments": { "id": 7 }
  }
}

create_case_status

Create a new case status.

Arguments

Field	Required	Type	Description
name	true	String	Case status name
description	false	String	Case status description
priority	false	Integer	Display priority
parent_id	false	Integer	Parent status ID for hierarchy

Returns the created case status object.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_case_status",
    "arguments": {
      "name": "Under Review",
      "priority": 3,
      "parent_id": 1
    }
  }
}

update_case_status

Update an existing case status.

Arguments

Field	Required	Type	Description
id	true	Integer	The case status ID to update
name	false	String	New case status name
description	false	String	New case status description
priority	false	Integer	New display priority
parent_id	false	Integer	New parent status ID

Returns the updated case status object.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_case_status",
    "arguments": {
      "id": 7,
      "name": "In Review",
      "priority": 4
    }
  }
}

list_hierarchical_case_statuses

List case statuses in a parent-child hierarchy. Takes no arguments.

Response

Returns an object with an items array. Each element is a root status with optional nested children (same structure), forming a tree.

Field	Type	Description
items	Array	Root-level statuses
items[].id	Integer	Case status ID
items[].name	String	Case status name
items[].description	String	Case status description
items[].priority	Integer	Display priority
items[].parent_id	Integer	Parent status ID, if any
items[].children	Array	Nested child statuses (recursive shape)

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_hierarchical_case_statuses",
    "arguments": {}
  }
}

Response

{
  "items": [
    {
      "id": 1,
      "name": "Open",
      "description": "New matters",
      "priority": 1,
      "children": [
        {
          "id": 7,
          "name": "Under Review",
          "priority": 2,
          "parent_id": 1,
          "children": []
        }
      ]
    }
  ]
}

reorder_case_statuses

Bulk update case status priorities.

Arguments

Field	Required	Type	Description
items	true	Array	List of status priority updates
items[].id	true	Integer	Case status ID
items[].priority	true	Integer	New priority value

Response

{ "status": "reordered" }

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "reorder_case_statuses",
    "arguments": {
      "items": [
        { "id": 1, "priority": 1 },
        { "id": 7, "priority": 2 },
        { "id": 3, "priority": 3 }
      ]
    }
  }
}

---

Webhooks

list_webhooks

List all webhooks configured for the company. Takes no arguments.

Response Fields

The structured result is an object with an items array. Each element describes one webhook.

Field	Type	Description
items	Array	Webhook entries
items[].id	Integer	Webhook ID
items[].name	String	Webhook name
items[].url	String	Destination URL
items[].enabled	Boolean	Whether the webhook is enabled
items[].event_types	Array	Subscribed event types
items[].case_type_ids	Array	Case type filters
items[].campaign_ids	Array	Campaign filters
items[].api_key_id	Integer	API key used for delivery
items[].last_delivery_status	String	Status of last delivery
items[].last_http_status	Integer	HTTP status of last delivery
items[].last_attempt_at	String	Timestamp of last delivery attempt

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_webhooks",
    "arguments": {}
  }
}

Response

{
  "items": [
    {
      "id": 12,
      "name": "Case Updates",
      "url": "https://example.com/webhooks/kayse",
      "enabled": true,
      "event_types": ["case_created", "case_updated"],
      "case_type_ids": [3],
      "campaign_ids": [],
      "last_delivery_status": "success",
      "last_http_status": 200,
      "last_attempt_at": "2025-06-15T14:30:00Z"
    }
  ]
}

get_webhook

Get a single webhook by ID.

Arguments

Field	Required	Type	Description
id	true	Integer	The webhook ID

Returns the webhook object (same fields as each element of list_webhooks's items array, except delivery status fields).

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_webhook",
    "arguments": { "id": 12 }
  }
}

create_webhook

Create a new webhook.

Arguments

Field	Required	Type	Description
name	true	String	Webhook name
url	true	String	Webhook destination URL
enabled	false	Boolean	Whether the webhook is enabled
event_types	false	Array	Subscribed event types. Empty means all supported events
case_type_ids	false	Array	Optional case type filters
campaign_ids	false	Array	Optional campaign filters
api_key_id	false	Integer	Optional API key ID for delivery

Returns the created webhook object.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_webhook",
    "arguments": {
      "name": "Case Updates",
      "url": "https://example.com/webhooks/kayse",
      "enabled": true,
      "event_types": ["case_created", "case_updated"]
    }
  }
}

update_webhook

Update an existing webhook.

Arguments

Field	Required	Type	Description
id	true	Integer	The webhook ID to update
name	true	String	Webhook name
url	true	String	Webhook destination URL
enabled	false	Boolean	Whether the webhook is enabled
event_types	false	Array	Subscribed event types
case_type_ids	false	Array	Optional case type filters
campaign_ids	false	Array	Optional campaign filters
api_key_id	false	Integer	Optional API key ID for delivery

Returns the updated webhook object.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_webhook",
    "arguments": {
      "id": 12,
      "name": "Case Updates v2",
      "url": "https://example.com/webhooks/kayse",
      "enabled": true
    }
  }
}

list_webhook_logs

List recent delivery logs for a webhook.

Arguments

Field	Required	Type	Description
id	true	Integer	The webhook ID

Response Fields

The structured result is an object with an items array. Each element is one delivery log entry.

Field	Type	Description
items	Array	Delivery log entries
items[].id	Integer	Log ID
items[].delivery_id	Integer	Delivery ID
items[].event_type	String	Event type
items[].event_key	String	Event key
items[].destination_url	String	Destination URL
items[].triggered_by	String	Trigger source
items[].attempt_number	Integer	Delivery attempt number
items[].http_status	Integer	HTTP response status code
items[].duration_ms	Integer	Delivery duration in milliseconds
items[].success	Boolean	Whether delivery succeeded
items[].error_message	String	Error message (on failure)
items[].request_headers	Object	Request headers sent
items[].request_payload	Object	Request payload sent
items[].response_body	String	Response body received
items[].created_at	String	Log timestamp (ISO 8601)

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_webhook_logs",
    "arguments": { "id": 12 }
  }
}

Response

{
  "items": [
    {
      "id": 456,
      "delivery_id": 789,
      "event_type": "case_updated",
      "event_key": "case:42",
      "destination_url": "https://example.com/webhooks/kayse",
      "triggered_by": "api",
      "attempt_number": 1,
      "http_status": 200,
      "duration_ms": 145,
      "success": true,
      "request_headers": {},
      "request_payload": {},
      "created_at": "2025-06-15T14:30:00Z"
    }
  ]
}

test_webhook

Queue a test delivery for a webhook.

Arguments

Field	Required	Type	Description
id	true	Integer	The webhook ID

Response

{ "status": "test queued" }

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "test_webhook",
    "arguments": { "id": 12 }
  }
}

replay_webhook_log

Replay a previous webhook delivery log entry.

Arguments

Field	Required	Type	Description
id	true	Integer	The webhook ID
log_id	true	Integer	The webhook log ID to replay

Response

{ "status": "replay queued" }

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "replay_webhook_log",
    "arguments": { "id": 12, "log_id": 456 }
  }
}

---

Admins

list_admins

List admins (staff/users) for the company. Supports pagination and keyword search.

Arguments

Field	Required	Type	Description
page	false	Integer	Page number (1-based). Defaults to 1
per_page	false	Integer	Items per page. Defaults to 25
key	false	String	Search keyword to filter admins by name, email, or phone

Response Fields (list)

Field	Type	Description
id	Integer	Admin ID
full_name	String	Admin full name
email	String	Email address
phone	String	Phone number
role	String	Company role

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_admins",
    "arguments": { "key": "john" }
  }
}

get_admin

Get a single admin by ID with full role and scope details.

Arguments

Field	Required	Type	Description
id	true	Integer	The admin ID

Response Fields (detail)

Field	Type	Description
id	Integer	Admin ID
full_name	String	Admin full name
email	String	Email address
phone	String	Phone number
role	String	Company role
status	Integer	Account status
global_role	String	Global role
scope_ids	Array	Scope IDs the admin has access to
scope_names	Array	Scope names the admin has access to
company_id	Integer	Company ID
last_active_company	Integer	Last active company ID

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_admin",
    "arguments": { "id": 5 }
  }
}

---

Audit Logs

list_audit_logs

List audit log entries for the company. Supports filtering by case, client, and action.

Arguments

Field	Required	Type	Description
page	false	Integer	Page number (1-based). Defaults to 1
per_page	false	Integer	Items per page. Defaults to 25
case_id	false	Integer	Filter by case ID
client_id	false	Integer	Filter by client ID
action	false	String	Filter by action type (e.g. create, update, delete)

Response Fields

Field	Type	Description
total	Integer	Total number of matching records
page	Integer	Current page
page_size	Integer	Items per page
logs	Array	Array of audit log entries
logs[].created_at	String	Timestamp (ISO 8601)
logs[].actor	String	Actor identifier
logs[].actor_name	String	Actor display name
logs[].action	String	Action performed
logs[].record_database_name	String	Affected resource type
logs[].record_database_id	String	Affected resource ID
logs[].source	String	Action source

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_audit_logs",
    "arguments": {
      "case_id": 42,
      "action": "update"
    }
  }
}

Response

{
  "total": 15,
  "page": 1,
  "page_size": 25,
  "logs": [
    {
      "created_at": "2025-06-15T14:30:00Z",
      "actor": "admin",
      "actor_name": "John Smith",
      "action": "update",
      "record_database_name": "cases",
      "record_database_id": "42",
      "source": "dashboard"
    }
  ]
}

---

Current Write Scope

MCP currently exposes read tools, create and update tools, and selected operational actions. Delete operations are not currently exposed through MCP.

Permissions and Access Control

The MCP server uses the same authentication, company scoping, and access controls as the Public API.

• API keys are passed with Bearer authentication
• Tool results are restricted to the company associated with the API key
• Existing role and scope restrictions continue to apply to the underlying data
• MCP does not bypass webhook, case-type, or case-status validations used elsewhere in Kayse AI

Configuration

To use Kayse AI with Claude Desktop or other MCP clients, you'll need to configure the MCP server settings. See the MCP Integration Guide for detailed setup instructions.

TIP

The MCP server uses the same authentication and permissions as the Public API. Make sure your API key has the necessary permissions for the operations you want to perform.