MCP tools and API endpoints
Required inputs, defaults and REST and CLI equivalents for all 25 MCP tools.
Artie exposes 25 tools for connection checks, discovery, private conversation, tasks, files and results. The same services are available through the versioned REST API; the tables below show each input and its CLI equivalent.
On this page
Overview
Reference notation: A is an Artisan UUID, T a task UUID, RUN a run UUID, F a file UUID and K an 8–128-character idempotency key. R is the task’s current integer revision. PAGE means offset (default 0), maxChars (default 12,000, maximum 24,000) and optional sourceVersion. Replace every placeholder with facts returned to your authorized session. Paths below are relative to /api/v1. Optional release-dependent fields must exist in your serving schema before use.
REST paths below are relative to /api/v1. CLI examples use the selected profile; append --profile work --json as appropriate. There is no direct CLI read_image command: the CLI downloads the original instead.
| MCP tool | REST method and normal response | Inputs and defaults | CLI equivalent and differences |
|---|---|---|---|
1 message_artisan | POST /artisan-messages / 202 | artisanId,text,K; conversationId? | artie artisan message --artisan A --instructions-file request.txt --key K; add --conversation C for follow-up. |
2 get_artisan_message | GET /artisan-messages/{messageId} / 200 | conversationId,messageId,PAGE | artie artisan message-result M --conversation C --offset 0 --max-chars 12000 --source-version V |
3 read_personal_instructions | GET /artisans/{artisanId}/personal-instructions / 200 | artisanId only | artie artisan instructions --artisan A |
4 connection_status | GET /me / 200 | {} | artie whoami; artie connections status; bare artie connections also reads identity. |
5 list_artisans | GET /artisans / 200 | q?,cursor?,limit=25 (1–50),includeStarterCatalog? | artie artisans --query research --limit 25 --cursor C --starter-catalog |
6 search_artie | POST /search / 200 | q,kinds (1–6); artisanId?,includeSkillContent=false,limit=20 (1–20),requestId? | artie search 'product notes' --type knowledge --type files --artisan A --limit 20; CLI has no includeSkillContent/requestId flag. |
7 delegate_task | POST /tasks / 202 | artisanId,instructions,K; title?,acceptanceCriteria?,inputRefs=[],timeZone=UTC,schedulePhrase?,scheduleEnd?,ongoing=false,responsibility? | artie task create --artisan A --instructions-file brief.txt --key K; alias task delegate; optional flags listed below. CLI defaults timezone to local OS timezone. |
8 list_tasks | GET /tasks / 200 | scope=mine; current canonical task filters below | artie task list --scope mine --query text --status needs_you --limit 25 --cursor C plus supported filters below. |
9 get_task | GET /tasks/{taskId} / 200 | taskId,includeInstructions=false,includeResolvedFiles?,resultCursor?,relatedCursor? | artie task show T --all --resolved-files; --all includes instructions only, no detail cursor controls. |
10 get_task_runs | GET /tasks/{taskId}/runs or /runs/{runId} / 200 | taskId,runId?,cursor?,limit=5 (1–25) | artie task runs T --limit 5 --cursor C; artie task run T RUN; artie task evidence T --run RUN. evidence is an alias of run/history reader, not a separate evidence exporter. |
11 get_task_result | GET /tasks/{taskId}/result / 200 | taskId,runId?,textCursor?,fileCursor?,artifactCursor?,effectCursor?,emailCursor?,limit=20 (1–20),maxChars=12000 (1–24000) | artie task result T --run RUN --all; without --all, --cursor only sets textCursor; other collection cursor flags absent. |
12 add_task_input | POST /tasks/{taskId}/inputs / 200 | taskId,kind,content,R,K; answer: runId?,inputRefs=[]; refine: inputRefs? | artie task input T --kind answer --file answer.txt --run RUN --expected-revision R --key K; artie task refine T --file full-brief.txt --expected-revision R --key K; refine --append fetches full brief and revision. |
13 control_task | POST /tasks/{taskId}/controls / 200 | taskId,control,R,K; pause/resume/cancel/retry/reopen: runId?; schedule-propose: phrase,timeZone; schedule-end: end (typed or null); schedule-cancel: no extras; set-ongoing: ongoing boolean | artie task pause T --expected-revision R --key K (and other verbs). If revision omitted, CLI reads current task. Schedule and ongoing examples below. |
14 get_usage | GET /usage / 200 | {} | artie usage; guests denied, admin billing management fact only. |
15 doctor | GET /doctor / 200 | {} | artie doctor; CLI adds profile/origin/credentialFamily, public health and identity to backend doctor. |
16 list_files | GET /files / 200 | query="" (≤160),after? (≤120),fileId?; no limit | artie files list --query notes --cursor C; CLI no fileId list selector. |
17 get_file | GET /files/{fileId} / 200 | fileId only; no revision selector | artie files show F; choose returned revision for content/text. |
18 get_artifact | GET /tasks/{taskId}/artifacts/{artifactId} / 200 | taskId,artifactId; no runId/revision | No standalone CLI metadata command. Artifact metadata available in artie task result T --run RUN --all. |
19 read_email | GET /tasks/{taskId}/runs/{runId}/emails/{emailId} / 200 | taskId,runId,emailId,offset?,maxChars? (1–24000),sourceVersion? (≤256) | artie task email T EMAIL --run RUN --offset 0 --max-chars 24000 --source-version V; CLI maxChars defaults 24000. |
20 upload_file | POST /files/inline / 201 | name,mime,encoding=utf8|base64,content,K; explicit decoded bytes ≤256 KiB | artie files upload path --mime type --key K uses raw POST /files, ≤10 MiB; no native inline-upload CLI verb. |
21 read_context | POST /context/read / 200 | memory: kind,path,PAGE; skill: kind,name,PAGE; artisan: kind,artisanId,PAGE | artie context read /notes.md --kind memory; artie context read 'Research procedure' --kind skill; artie context read A --kind artisan; common paging flags. |
22 read_file | GET /files/{fileId}/text / 200 | fileId,revision?,PAGE | artie files read F --revision V --offset 0 --max-chars 24000 --source-version S |
23 list_memory | GET /memory / 200 | path?,afterId?; no limit | artie context lines /notes.md --cursor UUID; path can be omitted. |
24 read_artifact | GET /tasks/{taskId}/artifacts/{artifactId}/text / 200 | taskId,artifactId,revision?,PAGE | artie task read-artifact T ART --revision V --offset 0 --max-chars 24000 --source-version S |
25 read_image | POST /images/read / 200 | file: kind=file,fileId,revision?; artifact: kind=artifact,taskId,artifactId,revision? | No native CLI image display command. artie files download F --output original.png or artie task download T ART --output original.png obtains original bytes. |
MCP argument examples for every tool
These are argument templates for a compatible MCP client's tools/call. Replace every placeholder before sending valid JSON, including numeric CURRENT_REVISION. Do not send the illustrative placeholder strings as UUIDs. Optional arguments are shown where they make a useful difference; consult the served schema for the complete contract.
| Tool | Example arguments |
|---|---|
message_artisan | {"artisanId":"ARTISAN_UUID","text":"Summarize my selected project notes privately.","idempotencyKey":"message-request-001"}; add returned conversationId for a follow-up. |
get_artisan_message | {"conversationId":"CONVERSATION_UUID","messageId":"MESSAGE_UUID","offset":0,"maxChars":12000} |
read_personal_instructions | {"artisanId":"ARTISAN_UUID"} |
connection_status | {} |
list_artisans | {"q":"research","limit":25,"includeStarterCatalog":true} |
search_artie | {"q":"product decisions","kinds":["knowledge","files"],"limit":10}; optional artisanId, includeSkillContent, requestId. |
delegate_task | {"artisanId":"ARTISAN_UUID","instructions":"Summarize the selected notes with sources.","inputRefs":[],"timeZone":"UTC","idempotencyKey":"task-request-001"} |
list_tasks | {"scope":"mine","status":["needs_you"],"limit":25}; use returned cursor for subsequent pages. |
get_task | {"taskId":"TASK_UUID","includeInstructions":true}; supported releases may add includeResolvedFiles:true. |
get_task_runs | {"taskId":"TASK_UUID","limit":5}; add runId to select one exact run, or cursor for history. |
get_task_result | {"taskId":"TASK_UUID","runId":"RUN_UUID","limit":20,"maxChars":12000} |
add_task_input | {"kind":"answer","taskId":"TASK_UUID","runId":"RUN_UUID","content":"Use the revised deadline in the attached notes.","inputRefs":[],"expectedRevision":CURRENT_REVISION,"idempotencyKey":"answer-request-001"} |
control_task | {"control":"pause","taskId":"TASK_UUID","expectedRevision":CURRENT_REVISION,"idempotencyKey":"pause-request-001"} |
get_usage | {} |
doctor | {} |
list_files | {"query":"notes"}; pass returned nextCursor as after, or select optional fileId. This tool has no arbitrary limit parameter. |
get_file | {"fileId":"FILE_UUID"}; this metadata tool has no revision input. |
get_artifact | {"taskId":"TASK_UUID","artifactId":"ARTIFACT_UUID"}; no runId argument. |
read_email | {"taskId":"TASK_UUID","runId":"RUN_UUID","emailId":"EMAIL_UUID","offset":0,"maxChars":12000} |
upload_file | {"name":"notes.txt","mime":"text/plain","encoding":"utf8","content":"Fictional project notes.","idempotencyKey":"upload-request-001"} |
read_context | {"kind":"memory","path":"/project-notes.md","offset":0,"maxChars":12000}; skill uses name; artisan uses artisanId. |
read_file | {"fileId":"FILE_UUID","revision":"RETURNED_REVISION","offset":0,"maxChars":12000} |
list_memory | {"path":"/project-notes.md"}; next page uses returned nextCursor as afterId. |
read_artifact | {"taskId":"TASK_UUID","artifactId":"ARTIFACT_UUID","revision":"RETURNED_REVISION","offset":0,"maxChars":12000} |
read_image | {"kind":"file","fileId":"FILE_UUID","revision":"RETURNED_REVISION"}; task artifact variant is {"kind":"artifact","taskId":"TASK_UUID","artifactId":"ARTIFACT_UUID","revision":"RETURNED_REVISION"}. |
Common limits: task instructions 100,000 characters; optional title 240; up to 20 acceptance criteria of 1,000 characters each; selected inputs up to 20 files plus eight knowledge sources without duplicate identities. Text-page maxChars is 1–24,000, default 12,000, and offset is nonnegative. Task result pages support independent textCursor, fileCursor, artifactCursor, effectCursor and emailCursor. Task detail separately uses resultCursor and relatedCursor.
Task lists accept scope: "mine" | "accessible", optional artisanId, parentId, responsibilityId, section, q, status, includeSubtasks, includeDone, showBackground, workOnly, paused, failed, and the bounded fields in the served schema. accessible remains permission-scoped; it is not a way to read coworkers' private work.
Need help with your workspace?
Contact support