MCP tools

The Kadmo MCP server at https://app.kadmo.ai/mcp exposes 26 tools in Kadmo v1.1.0. This page lists every one, grouped by what it works on, with its parameters. How to connect a client is on MCP server.

Every tool acts as the signed-in member, on that member's account only — it can never see or change another account. A tool that refuses answers with a machine code first (for example admin_required (403)) and a reason the model can act on.

Access at a glance

Access	Tools
Read-only, any member	list_agents, get_agent_status, get_task, review_tasks, get_run_transcript, list_playbooks, get_playbook, get_issue_type_routing, list_workflows, get_pack, list_pack_files, read_pack_file
Starts or records work, any member	dispatch_agent_job, run_workflow, queue_workflow, queue_jobs, work_on_task, publish_task_review, sync_pack
Changes account content, Admin only	manage_playbook, set_issue_type_routing, manage_workflow, manage_role, write_pack_file, scaffold_pack_node, delete_pack_node

The Admin-only tools and sync_pack are refused once a trial has ended, as are the four dispatch tools (dispatch_agent_job, run_workflow, queue_workflow, queue_jobs), which also count against the account's daily usage cap. Each tool also tells your client whether it only reads, whether it can delete or start work, and whether it reaches outside Kadmo, so the client can decide what to confirm with you.

Two kinds of workflow id

list_workflows returns workflow names such as se-work — the ids run_workflow, queue_workflow, queue_jobs, dispatch_agent_job and manage_workflow take. A playbook step's workflow_id is a different kind of id, such as agent_se_work, listed by get_pack with include: ["agent_workflows"]. Using one where the other is expected fails.

Fleet and dispatch

Your agents and the single-workflow jobs that run on them.

list_agents

Lists every agent in your account with its status, Claude Code session count, activity, active job and job PID.

No parameters.

get_agent_status

One agent's health, browser connection, running workflows, Claude Code sessions and system metrics. Optionally includes a fresh screenshot of the agent's desktop as an image.

Parameter	Type	Required	Meaning
agent	string	yes	Agent name or number, for example 5 or agent-5
include_screenshot	boolean	no	true adds a fresh desktop screenshot. Default false — leave it off for cheap polling

dispatch_agent_job

Sends a workflow to a named agent and creates a tracked job you can follow in the app. The agent is matched loosely: 5, agent-5 or the full name.

Parameter	Type	Required	Meaning
agent	string	yes	Agent name or number
workflow_id	string	yes	The workflow to run, by name (for example qa-validate, se-work)
params	object	no	Workflow parameters as key-value pairs. Most workflows need ticket_url; some also accept hint
effort	string	no	Effort tier slug (medium, high, max or a custom tier). Omitted or unknown falls back to the workflow's, the agent's, then the account's default
workspace_slug	string	no	Workspace to run in; it must be assigned to the named agent. Preferred over entry_path
entry_path	string	no	Older alternative to workspace_slug: a path on the agent such as ~/workspace. Ignored when workspace_slug is set

run_workflow

Runs a named workflow immediately as a job; Kadmo picks the agent unless you name one. For agent workflows on tickets, queue_jobs is usually the better fit.

Parameter	Type	Required	Meaning
workflow	string	yes	Exact workflow name from list_workflows
ticket_url	string	no	Ticket URL or bare key
agent	string	no	Agent to run on
effort	string	no	Effort tier slug. Omitted or unknown falls back to the workflow's, then the account's default
hint	string	no	Extra context or instructions for the agent

queue_workflow

Same as run_workflow, but adds the job to the dispatch queue instead of running it now.

Parameter	Type	Required	Meaning
workflow	string	yes	Exact workflow name from list_workflows
ticket_url	string	no	Ticket URL or bare key
agent	string	no	Agent to run on
effort	string	no	Effort tier slug. Omitted or unknown falls back to the workflow's, then the account's default
hint	string	no	Extra context or instructions for the agent

queue_jobs

Queues one workflow for one or more tracker tickets in a single call — "run se-work for PROJ-42 and PROJ-43".

Parameter	Type	Required	Meaning
workflow_id	string	yes	Exact workflow name from list_workflows (for example se-work, qa-validate)
tickets	array of objects	yes	At least one ticket. Each has key (string, required — for example PROJ-42) and url (string, optional — derived from the key when omitted)
effort	string	no	Effort tier slug. Omitted or unknown falls back to the workflow's, then the account's default
agent	string	no	Preferred agent
hint	string	no	Extra instructions or context for the agent

Tasks, runs and reviews

The task pool, playbook runs and their evidence.

work_on_task

Runs one whole playbook — several gated steps and roles — for one ticket. With Jira connected it pools the ticket in Tasks with your options, approves it and lets the scheduler start it once its in-pool blockers are done. Without Jira it says so and runs the playbook without a ticket, using the ticket text as context. If a run already drives the ticket, it reports that run instead of starting another. The reply includes the ticket's priority when the tracker has one; priority is never set here.

Parameter	Type	Required	Meaning
ticket	string	yes	Jira ticket key (for example PROJ-123) or its browse URL. Without Jira, this text becomes the run's context
playbook	string	yes	Playbook slug (for example bug-fix, feature-impl) or numeric id
effort	string	no	Effort tier slug for every step of the run. Omitted: each step uses its own default
sync_jira_status	boolean	no	Whether the run moves the ticket's status as it progresses. Defaults to the playbook's setting; always off without a ticket
validate	boolean	no	Whether a validation agent checks the ticket's acceptance criteria after the run and flags gaps in Tasks. Omitted: the account default
hint	string	no	Extra instructions passed to every step
workspace	string	no	Workspace slug to run in, instead of the one linked to the ticket's project
force	boolean	no	Pool and approve even when a run already drives the ticket; the live run is adopted, not duplicated. Default false

get_task

A ticket's full execution history: every playbook run (the whole rework chain), each step's role, workflow, job, status, verdict, cost and agent, gate comments, agent summaries and activity. Includes the ticket's tracker priority. Compact — it never returns transcript bodies.

Parameter	Type	Required	Meaning
task	string	yes	Ticket key (for example PROJ-123) or a numeric task-pool id
runs	all | latest	no	all (default) for every run, latest for the newest only
comments	excerpt | full | none	no	Gate-comment detail. Default excerpt
format	markdown | json	no	Default markdown

review_tasks

The task pool's "needs your attention" list in one call, each task with the same run story as get_task, plus its validation flag, blockers, priority and links — enough to triage the whole pool at once.

Parameter	Type	Required	Meaning
scope	needs_action | active | all	no	needs_action (default): pending approvals, paused runs, dead blockers and flagged done tasks. active adds running and waiting tasks. all is the whole pool
runs	all | latest	no	Per-task run history. Default all
comments	excerpt | full | none	no	Gate-comment detail. Default excerpt
format	json | markdown	no	Default json

get_run_transcript

One step's Claude Code session transcript, within a byte limit — the only tool that returns transcript bodies. Address it by job, or by run and step. A missing transcript answers "unavailable".

Parameter	Type	Required	Meaning
job	integer	no	Job id
run	integer	no	Run id; pair it with step
step	integer	no	Step index. Defaults to the first step that has a transcript
mode	summary | tail | head | grep | full	no	Default tail. summary returns the stored summary without reading the transcript
lines	integer	no	Line count for tail and head. Default 80
pattern	string	no	Search pattern for grep
max_bytes	integer	no	Byte limit for the returned text, at most 5 MB. Default 262144

publish_task_review

Publishes review suggestions for tasks back to the Tasks page, built up over several calls: call without review_id to start a new review (it replaces your account's previous open review), pass the returned id to add more, and send complete: true to finish. Invalid rows come back in rejected with a reason; valid ones are kept. The reply includes a link to the review in the app.

Parameter	Type	Required	Meaning
review_id	string	no	Omit to start a review; pass the returned id to add to it or complete it
suggestions	array of objects	no	Suggestions to add — fields below
groups	object	no	Consolidation groups by group key, each with title, note, playbook and effort. Merged with groups already on the review
complete	boolean	no	true on the last call to finish the review

Each suggestion:

Field	Type	Required	Meaning
ticket	string	yes	Key of a task in your pool
action	verify | wait | reopen | consolidate | dismiss | none	yes	verify and reopen re-run the delivery (put the instruction in hint); wait blocks on another task (needs blocker); consolidate joins a group (needs group); dismiss mutes the flag; none means a person must decide
confidence	integer	yes	0–100: how likely this action is right
rationale	string	no	One-line reason shown on the suggestion
hint	string	no	Re-run instruction for verify and reopen
group	string	no	Group key for consolidate; must exist in groups
blocker	string	no	For wait: the key of the task this one waits on, itself in your pool
evidence	object	no	run_id, step_index and comment_url the suggestion is based on, shown as a source link

Playbooks and routing

The multi-step playbooks Kadmo runs, and which playbook each issue type starts.

list_playbooks

Your playbook catalog: the built-in playbooks (Bug Fix, Feature Implementation, Hotfix, …) and your own, enabled and disabled, with slug, roles, steps and your account's run counts. Use it to confirm a slug before work_on_task — a copy such as bug-fix-copy is a different playbook from bug-fix.

No parameters.

get_playbook

One playbook's full definition — every step with all its fields — plus whether you may edit it. Built-in playbooks are readable but not editable; duplicate one to change it.

Parameter	Type	Required	Meaning
playbook	string	yes	Exact slug (for example bug-fix) or numeric id — not the display name
format	json | markdown	no	Default json

manage_playbook

Creates, duplicates, updates or deletes a playbook, with the same rules as the playbook Library in the app. Admin only.

• create needs name and steps; the slug is derived from the name and never changes afterwards (rename with name).
• duplicate copies a playbook or a built-in one — the only way to change a built-in playbook. Without steps it is an exact copy.
• update changes only the fields you pass. steps replaces the whole list, so read the playbook first.
• delete removes it, or disables it instead when runs or automations still use it; the reply says which, and lists issue types that now fall back to their default playbook.

Steps are validated one error at a time, naming the step and field.

Parameter	Type	Required	Meaning
action	create | duplicate | update | delete	yes	What to do
playbook	string	no	Slug or numeric id to act on (for duplicate, the source). Required for update, delete and duplicate
name	string	no	Display name. Required for create
description	string or null	no	Free text; blank or null clears it
steps	array of objects	no	The complete, ordered step list — fields below. Required for create
sync_jira_status_default	boolean	no	Whether runs move the ticket's status by default. Default true on create
is_enabled	boolean	no	Whether the playbook can be started. false retires it without losing run history
default_effort	string or null	no	Default effort tier for the steps; must exist in your account. Empty or null inherits
default_agentic_app	string or null	no	Default agent app for the steps. Empty or null inherits

Each step:

Field	Type	Meaning
kind	agent | end	agent (default) dispatches work; end is a final status-or-wait step, allowed only last
role	string	Role that runs the step (se, qa, pm, …). Required on agent steps
workflow_id	string	Agent workflow id (for example agent_se_work) from get_pack with include: ["agent_workflows"]. Required on agent steps
status_on_entry	string	Ticket status to set when the step starts, for example In Progress
delay_ms	integer	Wait before the step, in milliseconds
hint	string	Guidance added to the step's prompt
effort	string	Effort tier for this step
agentic_app	string	Agent app for this step
gate	object	Verdict routing, required on agent steps: pass (verdicts that advance), stop (verdict → final status: resolved, no_action, escalated or rework), pause (verdicts that wait for a person), retry (re-run the same step; only on agent_se_work with WORK_CONTINUE and agent_qa_pass with HANDOFF), loopback (send the run back to an earlier step)
max_attempts	integer	Total tries for a retry step, 1–10. Default 10
loopback_to	integer	Index (from 0) of the earlier step a loopback verdict returns to
max_loops	integer	How often the step may send the run back, 1–5. Default 2

get_issue_type_routing

Which playbook each tracker issue type starts when a ticket is pooled: your saved mappings merged with the defaults (Bug → bug-fix, Story and Task → feature-impl, Hotfix → hotfix), with the outcome that actually applies. The tracker (Jira or Linear) is the one your account is connected to. On Linear, the issue type is the ticket's first label.

Parameter	Type	Required	Meaning
include_tracker_types	boolean	no	Also list the tracker's live issue types, so types with no mapping appear. Default true; false answers from defaults and saved rows only

set_issue_type_routing

Sets or clears the playbook one issue type starts — the same as the Issue type routing page in the app. Admin only. Clearing returns the type to its default. Setting a type to its own default pins it, so it no longer follows future changes to the defaults.

Parameter	Type	Required	Meaning
action	set | clear	yes	set binds the type; clear removes your mapping
issue_type	string	yes	The issue type, for example Bug. Case does not matter; types your tracker does not define are allowed
mapping	run | skip	no	Required with set: run starts playbook; skip creates no task for this type
playbook	string	no	Slug or numeric id of an enabled playbook. Required with mapping: "run"

Workflows and roles

list_workflows

Your workflows with id, version, enabled state, scope, description and required parameters. Disabled workflows are listed too and cannot be dispatched until re-enabled. Scope says who owns each: default (shared by every account — changing it gives you your own copy), account (your pack or your copy) or custom (created in the app).

No parameters.

manage_workflow

Creates a workflow, saves its YAML, enables or disables it for your account, or sets its dispatch defaults — the same as the Workflows page in the app. Admin only.

• Every save runs the same check the agents run; a failure lists each error's step, line and column, and nothing is committed. dry_run: true checks without saving.
• Saving a shared default workflow gives your account its own copy, and your copy is the one that runs. Disabling a shared default does the same; enabling it again returns you to the shared version.
• Changing a workflow's id is refused — create a new workflow instead.
• If your skill pack works through pull requests, a save is not live until the pull request is merged. A saved change reaches your agents within about five minutes.

Parameter	Type	Required	Meaning
action	create | edit_source | enable | disable | set_defaults	yes	What to do
workflow	string	no	Workflow name from list_workflows or numeric id. Required for every action except create
content	string	no	The complete YAML. For edit_source the new body; for create the first version (its id must equal id)
base_sha	string	no	Required for edit_source: the token read_pack_file returned for this workflow, read just before
domain	string	no	create only: a domain registered in your pack
id	string	no	create only: the workflow id, which becomes its file name and dispatch name
title	string	no	create without content: the title of the starter file
role	string	no	create only: the role the new workflow declares, for example se
effort	string or null	no	set_defaults only: default effort tier; null or empty clears it
agentic_app	string or null	no	set_defaults only: default agent app, which must exist in your account; null or empty clears it
message	string	no	Commit message for create and edit_source
dry_run	boolean	no	create and edit_source: check only, save nothing. Default false

manage_role

Creates, updates or deletes an agent role — the same as the Roles page in the app. Admin only.

• create writes the role's instructions file (_roles/<slug>.md) to your skill pack; the reply's registered flag confirms the role exists. With pull requests, it exists only after the merge.
• update changes the label, colour, description and order only. The slug never changes, and the role's instructions are edited with read_pack_file and write_pack_file.
• delete is refused for the built-in ops role and for a role still used by workflows, agents or pack files (the reply shows where).

Parameter	Type	Required	Meaning
action	create | update | delete	yes	What to do
slug	string	yes	The role's permanent key: lowercase, up to 12 characters, starting with a letter (for example be, sre). other, all, auto and none are reserved
label	string	no	Display name. Required for create
color	string	no	One of violet, indigo, cyan, pink, purple, fuchsia, lime, slate. Default slate
description	string	no	One-line description; blank clears it
sort_order	integer	no	update only: position in role lists; lower comes first
domain	string	no	create only: create the role for one existing pack domain instead of the whole pack
delete_files	boolean	no	delete only: also remove the role's own files from the pack. Needs confirm
confirm	string	no	delete only: must equal slug to arm delete_files
message	string	no	Commit message for create and delete_files

Skill pack

Your account's skill pack — the knowledge agents work from — edited through git. See Skill packs.

How a write lands depends on your pack setup, not on the tool: a commit on the Kadmo-hosted repository, a push to your own repository, or a pull request that is not live until someone merges it. The reply says which. A landed change is live in Kadmo at once and reaches your agents within about five minutes. Writes use a conflict token: read a file, then pass its base_sha back unchanged; if the file changed in between, the write is refused with stale_base_sha (409) and the latest content, and nothing is committed.

get_pack

The starting point for any pack or playbook change: your pack repository and its sync state, whether Kadmo may write to it and what a write would do, and every skill domain with its readiness. Optional sections add the vocabularies authoring needs.

Parameter	Type	Required	Meaning
include	array of roles | agent_workflows | effort_tiers | agentic_apps	no	Extra sections: agent_workflows (the ids playbook steps use), effort_tiers, roles with their usage, agentic_apps (Admin only)

list_pack_files

Every file in your pack that can be edited, with its kind, size and base_sha.

Parameter	Type	Required	Meaning
domain	string	no	Only files under this domain, for example acme.example.com
kind	module_skill | role_playbook | workflow | manifest | index | domain | other	no	Only files of this kind
include_non_editable	boolean	no	Also list files Kadmo maintains itself (the root index.json), marked not editable. Default false
include_dirs	boolean	no	Also list each domain folder with the token a recursive delete_pack_node needs. Default false
limit	integer	no	Fewer rows than the default 500
format	markdown | json	no	Default markdown; use json when you will pass base_sha to a write

read_pack_file

One pack file's content and base_sha, by path — or a workflow's YAML by its name or id, including a shared default workflow. A path that does not exist yet reads as empty with an empty base_sha, which is the token for creating it.

Parameter	Type	Required	Meaning
path	string	one of path or workflow	Path inside the pack, for example acme.example.com/checkout/_skill.md
workflow	string	one of path or workflow	Workflow name or numeric id
max_bytes	integer	no	Byte limit, at most 524288. Default 262144
format	json | text	no	Default json, which keeps base_sha; text is cheaper for reading only

write_pack_file

Writes one pack file: .md, .yaml / .yml or skill-pack.json. Admin only. content is the complete new file, never a patch. For workflow YAML use manage_workflow instead.

Parameter	Type	Required	Meaning
path	string	yes	Path inside the pack; missing folders are created
content	string	yes	The complete new file. An empty string empties it
base_sha	string	yes	The token from read_pack_file, read just before. "" creates a new file
message	string	no	Commit message
create	boolean	no	Assert that the file is new
dry_run	boolean	no	Validate only, write nothing. Default false

scaffold_pack_node

Adds a new module or a whole new domain to your pack in one commit. Admin only. A domain gets its _skill.md, skill-pack.json and a starter _roles/qa.md, and is registered in the pack index.

Parameter	Type	Required	Meaning
kind	module | domain	yes	module adds one module under an existing domain; domain adds a new domain
host	string	yes	The domain, written like a host name (for example acme.example.com)
module	string	no	One lowercase segment, for example checkout. Required for module
message	string	no	Commit message

delete_pack_node

Deletes one pack file, or a whole domain folder, in one commit. Admin only. This cannot be undone from Kadmo — recovery means your pack repository's git history. The pack's root index.json and skill-pack.json cannot be deleted.

Parameter	Type	Required	Meaning
path	string	yes	A file, or with recursive a domain folder
base_sha	string	yes	The file's token, or the domain's token from list_pack_files with include_dirs: true
recursive	boolean	no	true deletes a whole domain. Default false
confirm	string	no	Required with recursive: the domain name, exactly
message	string	no	Commit message

sync_pack

Pulls your pack repository and refreshes Kadmo — the same as Sync Now in the app. Use it after a pull request was merged or someone pushed to the pack directly; your own writes already sync. It may wait behind a write in progress. Read status in the reply: error means some content is live and some is not, and workflows_invalid lists workflow files that fail the check.

No parameters. Open to every member.