Updated Sep 17, 2026

MCP Servers

What you'll learn

• What MCP is and how it connects AI coding agents to AutoTalk
• How to configure MCP in Codex and Claude Code
• What tools are available and how to use them

AutoTalk exposes an MCP (Model Context Protocol) server that gives AI coding agents direct access to your dynadata schemas, example documents, CRUD operations, and workflow testing. Tools like Codex and Claude Code can read your data models and build agents/workflows without copy-pasting schemas.

Prerequisites

You need an API token to authenticate with the MCP server. See API Tokens for how to create one.

The MCP endpoint is:

https://mcp.autotalk.io/v1

note

The public MCP host uses the same API-key authentication model as the rest of /v1/. External MCP clients like Codex and Claude Code should use x-api-key as shown below.

Authorization: Bearer is not supported — the key must be sent in the x-api-key header. Codex users: use the env_http_headers form shown below, not bearer_token_env_var. A wrong header name yields an opaque 401 unauthorized, so if you get a 401 with a valid key, check the header name first.

Codex setup

Start Codex with the AutoTalk MCP server configured for this session:

AUTOTALK_API_KEY="sk-YOUR-API-KEY" codex --config 'mcp_servers.autotalk_main.url="https://mcp.autotalk.io/v1"' --config 'mcp_servers.autotalk_main.env_http_headers={"x-api-key"="AUTOTALK_API_KEY"}'

warning

Keep the env_http_headers form shown above so Codex reads the token from AUTOTALK_API_KEY.

Claude Code setup

Register the AutoTalk MCP server and start Claude Code:

claude mcp add --transport http autotalk_main https://mcp.autotalk.io/v1 --header "x-api-key: sk-YOUR-API-KEY" && claude

Available tools

51 tools across 8 categories.

Documents & data (5)

Tool	Description	Tags
create_document Create document	Creates a new dynadata document — an agent, workflow, service, or any other dynadata type. Full description Creates a new dynadata document in the database. Returns the created document with its _id. Use this to persist agents, workflows, services, and other dynadata types for real testing. Returns the created document, including its `_id`. Any storage refs it contains are resolved into `structuredContent.mediaRefs` — NOT into the document body, and not under an `_mcp` key (that wrapper exists only on the resource-read path). THIS TOOL NEVER SENDS: a type='messages' create is persisted only. An outbound one (a `method` set, `createdBy` not 'contact', no `platformMid`) is stored with currentStatus='PENDING' rather than the delivery-shaped default, because nothing will dispatch it — use `send_message` to actually deliver.	—
delete_document Delete document	Soft-deletes (tombstones) a dynadata document by ID, excluding it from future reads without destroying it. Full description Soft-deletes (tombstones) a dynadata document by ID. The document will be excluded from future reads but can be recovered. Returns {deleted: true, tombstoned: true} — NOT the deleted document.	destructive
get_document Get document	Reads a single dynadata document by type and ID, respecting ACL scoping and excluding soft-deleted documents. Full description RETURNS the full document; storage refs it contains are resolved into `structuredContent.mediaRefs`, not into the document and not under `_mcp`. There is no field-projection parameter, so use query_documents with `fields` when you only need part of a large document. Reads a single dynadata document by type and ID. Respects ACL scoping and excludes tombstoned (soft-deleted) documents.	read-onlyidempotent
query_documents Query documents	Finds dynadata documents by field values using a structured filter tree, with optional sorting, paging, and related-document expansion. Full description Queries dynadata documents by structured filter tree. Returns matching documents with their _ids. Use this to find documents by field values before reading or updating them. The filterTree is a typed AST: each condition has {fieldPath, kind, operator, value}, and groups combine conditions with and/or. Example: {type: 'group', operator: 'and', children: [{type: 'condition', fieldPath: 'name', kind: 'string', operator: 'contains', value: 'acai'}]}. TO SEARCH BY CONTENT, filter on the text field itself — `contains` is the content-search operator. Do NOT page through a large collection chronologically looking for a match: add a `contains` condition and let the server find it. Example, finding messages in one conversation that mention a word: {type:'group',operator:'and',children:[{type:'condition',fieldPath:'conversationId',kind:'objectId',operator:'eq',value:'<id>'},{type:'condition',fieldPath:'body.text',kind:'string',operator:'contains',value:'refund'}]}. Always pair a content filter with a narrowing condition (conversationId, a date range, a status) — an unbounded contains scans the whole collection. `fieldPath` must be the REAL path in the stored document, which for union-typed fields is nested (message text lives at `body.text`, not `text`). When you are not certain of a path, call get_model_definition for the type FIRST — one call there is cheaper than a failed query plus a retry. Per-kind operator allowlist: string/array supports eq|ne|in|contains|equals|startsWith|endsWith; enum (select fields) supports eq|ne|in|equals; number/date supports eq|ne|gt|gte|lt|lte|in; boolean eq|ne; objectId/ref/refArray eq|ne|in. `kind` is accepted for readability but IGNORED — the real kind comes from the model schema, so a wrong kind never fails and a right one never rescues a bad fieldPath/operator pairing. contains/equals/startsWith/endsWith are case-insensitive LITERAL matches: regex metacharacters in `value` are escaped, not interpreted. Limits, all hard 400s: nesting depth 6, 100 conditions total, 64KB payload, 256 bytes per match value. Use `expand` to hydrate related documents in a single round-trip: pass [{field: 'contactId', as: '_contact', fields: ['name', 'avatar']}] to follow a ref/refArray field; the target collection is resolved server-side from the source model's ref declaration, the trusted ACL stage is injected automatically, and the inner `fields` array is allowlisted against the target model's exposed (non-denied) fields. Single-ref expansions emit one object under `as`; refArray expansions emit an array. RETURNS a bare ARRAY of documents — no wrapper object, no total count, no cursor. The only end-of-results signal is a page shorter than `limit`. If you only need HOW MANY, call count_documents instead — it takes the same filterTree and answers in one call; paging this tool to count rows wastes many round-trips. Storage refs found in the results are resolved into `structuredContent.mediaRefs`.	read-onlyidempotent
update_document Update document	Updates an existing dynadata document by ID — use it to iterate on agents, workflows, or any dynadata type between test runs. Full description RETURNS the full updated document (with _id). Storage refs it contains are resolved into `structuredContent.mediaRefs`, not into the document and not under `_mcp`. Updates an existing dynadata document by ID. Returns the updated document. Use this to iterate on agents, workflows, or any dynadata type between test runs.	destructive

Functions & workflows (5)

Tool	Description	Tags
execute_function Execute function	Executes a server-side function on a dynadata document or collection, handling ACL checks, argument validation, and method dispatch. Full description RETURNS whatever the function itself returns, unwrapped — the shape is function-specific, so read its `arguments` and description from list_functions first. Executes a server-side function on a dynadata document or collection. Handles ACL checks, argument validation, hidden conditions, and method dispatch. For document-scope functions, pass the document ID. For collection-scope functions, ID is optional.	destructive
get_workflow_run Get workflow run	Reports an API-started workflow run's status and, once terminal, its result, files, and logs. Full description RETURNS {runId, workflowId, mode, status, ok, result, files, logs, executionTimeMs, createdAt, startedAt, finishedAt} plus, when present, failedSteps, returnError, error{code, message, errorId}, skipReason and stepOutputs. Polls a workflow run started over the v1 API — the completion half of POST /v1/workflows/:id/run, returning the same document as GET /v1/workflows/:id/runs/:runId. `files` entries are storage refs usable with inspect_media, send_message attachments or dynadata file fields. Only API-started runs are visible (runSource 'api'): hook- and cron-triggered runs answer not_found here, deliberately — the same fence the /v1 twin applies. `stepOutputs` appears only when the run was started with includeStepOutputs. To OBSERVE a run from inside another workflow, prefer execute_workflow_manual's synchronous return (step(N).data.returnValue) over polling.	read-onlyidempotent
list_functions List functions	Lists the executable server-side functions for a dynadata type, with each one's scope, required ACL action, and argument schema. Full description RETURNS an array of {name, scope, aclAction, arguments:[{name, type, description, required, default, enum}]}; that `arguments` list is the contract for execute_function's `args`. Lists executable server-side functions for a dynadata type. Returns each function's name, scope (document or collection), required ACL action, and argument schema. UI-scope functions (frontend-only) are excluded. When 'id' is provided, the list is filtered to functions visible for that specific document.	read-onlyidempotent
run_code Run code	Runs sandboxed JavaScript or Python — the same executor the code workflow step uses, without the workflow envelope. Full description RETURNS {ok, result, files:[{name, bucket, fullPath, contentType, size}], logs:[{level, message}], executionTimeMs, error?:{code, message, retryable?}} — first-class sandboxed code execution (#218): the same executor the actions/code/execute workflow step uses, without the workflow envelope. language 'javascript': isolated V8 (console + SSRF-guarded fetch + files API, no Node.js APIs; timeout 100–30000 ms, memory 8–256 MB). language 'python': python3 in a throwaway container (--network=none) with a host-mediated SSRF-guarded fetch(url, method=, headers=, body=) → dict, same egress as the JS lane (timeout 1000–120000 ms, memory 128–2048 MB; pre-installed: openpyxl, python-docx, python-pptx, pdfplumber, pypdf, pandas, Pillow, reportlab, markitdown). `input` is a literal JSON value — JavaScript sees it as the `input` global, Python as `INPUT`. `inputFiles` are tenant storage refs [{bucket, fullPath, name?}] (max 10 / 20 MiB each / 24 MiB total) — JavaScript reads them via files.read(name) → base64, Python at /work/in/<name>. Return a value (JS) or write /work/out/output.json (Python) for `result` (max 2 MiB); write files via files.write(name, base64, {contentType?}) (JS) or /work/out/ (Python) — they come back as storage refs readable with inspect_media or GET /v1/storage/url. Guest errors do NOT raise a tool error: check `ok` and `error.code` (python_unavailable = lane not enabled in this environment; code_executor_busy = retry).	—
test_workflow Test workflow	Runs a manual workflow's steps inline against live company data — a real execution whose writes persist; only the execution record is skipped. Full description RETURNS {logs:[{level, message, meta, ...}], responses:[messages produced], spelArena, returnValue, returnError?} — `logs` is the per-step trace and `returnValue` is the evaluated returnExpression. `spelArena` is the full CEL evaluation arena: every step's actionContext lives under spelArena.context.tools.<toolId>.actions.<stepIndex> (the same object step(N) resolves), including code steps' `result`, `files` (storage refs — readable with inspect_media), `logs`, and `executionTimeMs`. Runs a manual workflow's steps inline — NOT a dry run: they execute FOR REAL against live company data and everything they write PERSISTS (dynadata rows, storage objects, sent messages, minted JWTs). Nothing is rolled back; only the workflow_executions record is skipped. Returns execution logs, step outputs, and the return value. Steps are capped at 25. For a one-off code snippet, prefer the run_code tool — same sandbox, no workflow envelope.	—

Files & media (10)

Tool	Description	Tags
begin_file_upload Begin file upload	Starts a two-step upload (up to 1 GB) and returns the signed PUT URL — or, above 90 MB, one URL per part — that you call yourself; use upload_file_inline if your client cannot make HTTP requests. Full description Starts a two-step file upload for this tenant and returns an uploadIntentId plus where to send the bytes. The PUTs are plain HTTP requests you must make yourself — this server has no tool that performs them, so an MCP-only client with no HTTP capability should use upload_file_inline instead. Files up to 90 MB return uploadMode "signed_put": {uploadIntentId, uploadMode, uploadUrl, requiredHeaders, bucket, fullPath, expiresAtMs} — execute ONE HTTP PUT of the file bytes to uploadUrl before expiresAtMs (15 minutes), using the requiredHeaders exactly as given, including Content-Type. Larger files (up to 1000 MB) return uploadMode "multipart_put": {uploadIntentId, uploadMode, uploadUrl: null, partSize, parts: [{partNumber, offset, size, uploadUrl, requiredHeaders}], bucket, fullPath, expiresAtMs} — PUT bytes [offset, offset+size) of the file to each part's uploadUrl with that part's requiredHeaders (no Content-Type), all before expiresAtMs (60 minutes); a failed part may be re-PUT to the same URL. Then call complete_file_upload with the uploadIntentId to finalize (for multipart it assembles the parts; if some are still missing it says so and you may retry after PUTting them). Path and bucket are chosen server-side — do not pass a fullPath. Subject to the tenant's storage quota; an abandoned upload's reservation is released when it expires.	—
complete_file_upload Complete file upload	Finalizes a two-step upload once the PUT has landed, verifying the stored object and billing the tenant for its bytes. Full description Finalizes a two-step upload after the HTTP PUT (or, for uploadMode multipart_put, every part PUT) succeeds. Verifies that the object landed in storage with the expected size/mime/metadata and emits the canonical finalize event (the tenant is billed for the bytes at this point). Returns {bucket, fullPath} suitable for inspect_media or to embed in a dynadata document field.	—
delete_file Delete file	Deletes a storage object owned by this tenant and releases its bytes from the storage quota. Full description RETURNS {deleted: true, existed, bucket, fullPath}. NOT idempotent — the object must still exist: a path that is already gone, mistyped, or another tenant's all fail alike with `not_found`. `existed:false` is only the narrow race where the object vanished between the ownership check and the delete; the call succeeds and the bytes are released. Deletes a storage object owned by this tenant. Verifies the object belongs to the tenant (by path prefix or customMetadata.companyId), then removes it and emits the canonical delete event so the byte count is released from storage quota. Remove references from documents first — otherwise the document field will still point at a missing object. REFUSES `protected_purpose` for objects a system invariant points at — avatars, company logos, widget/service icons, inbound and normalized chat media, link-preview and channel-emote caches. Deleting one of those breaks the referencing document rather than reclaiming anything; change the owning document (or delete it, which cascades) instead.	destructive
get_transcode_job Get media transform job	Returns a media transform job's status, progress and — once done — the storage ref of the converted file. Full description RETURNS {jobId, status, preset, progress, output, error, errorCode}. Once status is 'done', `output` is a {bucket, fullPath, contentType, sizeBytes, cached} ref you can pass to send_message, inspect_media or a document field. `output.cached` true means an existing derivative satisfied the job, so it cost nothing. On failure read `errorCode`: too_large, too_long, undecodable and output_too_large are PERMANENT for this (file, preset) pair — retrying re-spends and fails the same way.	read-onlyidempotent
get_transcription_job Get transcription job	Reports a transcription job's status and progress, and once finished, where its rendered transcript files were written. Full description RETURNS {jobId, status, progress, enginePath, providerType, diarized, speakerCount, outputs, error}. `outputs` holds storage full paths to the rendered transcript files, not the transcript text itself — read one with inspect_media. Returns a transcription job's status, progress and — once done — the storage full paths of the rendered transcript outputs.	read-onlyidempotent
inspect_media Inspect media	Reads a storage object's metadata and signed URL, inlining images and Office documents as model-readable content. Full description RETURNS {bucket, fullPath, name, uri, mimeType, size, mediaKind, updated, timeCreated, customMetadata, signedUrl}, plus `source` when read through a document and `analysis` when analysis='transcript'. Image dimensions and audio/video duration are NOT included — only byte `size` and `mimeType`. Images are additionally inlined as model-readable content (`imageInlined: true`, or `imageInlineError` if inlining failed). Reads a storage media reference from a dynadata document or direct {bucket, fullPath}. Returns metadata, a temporary signed URL, and model-readable image/file content when supported. Office documents (docx/xlsx/pptx families) are inlined as extracted plain text (`fileInlined: true`; spreadsheets render one CSV section per sheet). For document refs, pass type, id, and path (e.g. type='messages', id='...', path='body.file'). For audio messages, pass analysis='transcript' to produce a non-persistent on-demand transcription when none is stored.	—
prepare_spoken_text Prepare spoken text	Rewrites markdown or rich text into what a person would say out loud, ready to hand to synthesize_speech. Full description RETURNS {text, model} — text only, no audio. Rewrites markdown or rich text into what a person would SAY, then feed the result to synthesize_speech. This is not markdown stripping: a table has no spoken form, so stripping produces word soup rather than an answer. A small, cheap catalog model does the rewrite. Input is capped at 8000 characters; the rewrite is deliberately short and fits synthesize_speech's 4096-character input cap. Bills tokens_in/tokens_out on the platform key — not tts_ms.	—
synthesize_speech Synthesize speech	Turns text into an audio file stored in company storage and returns a ref to it — synchronously, so there is no job to poll. Full description RETURNS {bucket, fullPath, size, contentType, format, cache, billedMeter, billedMs} — the audio file EXISTS when this returns. Synchronous, unlike transcribe_storage_file: there is no job to poll. Turns text into an audio object under the company storage prefix. Use the returned {bucket, fullPath} with send_message attachments, dynadata file fields or inspect_media. Text is capped at 4096 characters (~700 words, ~5 minutes of speech) — there is NO server-side chunking or audio concatenation, so longer input is rejected rather than split. Markdown reads badly out loud; run prepare_spoken_text first when the text came from an LLM or a rich-text field. Platform voices bill tts_ms; a repeat of identical text within 10 minutes is a cache hit that skips the provider call and bills no tts_ms, but STILL writes and charges a new stored object. BYO voice profiles report their estimate on the internal, non-billed audio_ms_byok counter (check billedMeter before trusting billedMs) and are never cached.	—
transcribe_storage_file Transcribe storage file	Enqueues an asynchronous transcription job for an audio file in company storage; poll get_transcription_job for the result. Full description RETURNS {jobId, status, enginePath, providerType, diarized} IMMEDIATELY — the transcript is NOT in this response. Poll get_transcription_job with the returned jobId, then read the file it names under `outputs`. Enqueues an ASYNC transcription job for an audio file in company storage. Uses the given transcription profile (or the company default); diarize profiles return speaker-labeled outputs. Outputs (txt/srt/vtt/json) are written next to the source file as <name>.transcript.<jobId>.<ext> (job-keyed, so re-running the same audio never overwrites an earlier transcript); read the exact paths off the job's `outputs`. Poll get_transcription_job for progress. For transcribing a chat AUDIO MESSAGE use inspect_media with analysis='transcript' instead.	—
transform_storage_file Transform storage file	Enqueues an asynchronous job that re-encodes an audio/video file in company storage into a preset format; poll get_transcode_job for the output ref. Full description RETURNS {jobId, status, preset} IMMEDIATELY — the transformed file is NOT in this response. Poll get_transcode_job with the returned jobId, then read the ref it names under `output`. Enqueues an ASYNC job that re-encodes an audio/video object in company storage into a preset format. mp4 produces H.264/AAC video; ogg_opus, wav and flac_16k_mono produce audio — pointing an AUDIO preset at a VIDEO source extracts its soundtrack, which is the supported way to get audio out of a video. IMAGES are refused: use run_code with Pillow instead. Source must be under 512 MiB; video presets refuse media over 30 minutes and audio presets over 4 hours (the job fails with errorCode 'too_long' rather than running up a bill) — call inspect_media or the probe action first if you need to branch on duration. Billed on transcoding_ms; re-transforming the same source with the same preset is FREE because the derivative is cached against the source's content.	—

Messaging (1)

Tool	Description	Tags
send_message Send message to contact	Sends an outbound message on the tenant's connected channels, to either a conversation or a contact. Full description RETURNS a dispatch receipt: {_id, conversationId, contactId, channelId, type, status:'sent', platformMid, timestamp}. WARNING — `status` is a receipt field, not a stored one: the message document has no `status` field, and its delivery state lives in `currentStatus` whose enum is ERROR|PENDING|AUTOTALK_ACK|SERVER_ACK|DELIVERY_ACK|READ|DELETED|PLAYED — 'sent' is not among them. Do not feed this value back into a query; to follow delivery, re-read the message by its returned `_id` and look at `currentStatus`. Sends an outbound message on the tenant's connected channels. Accepts exactly one of {conversationId, contactId}. With contactId, the conversation is found-or-created on the contact's channel. THIS is the only tool that dispatches: `create_document` with type='messages' persists a row and sends nothing, which is why it stores an outbound create as currentStatus='PENDING'. Body shape per type: text={text}; image/audio/video/document/ptv={file:{bucket,fullPath}, text?=caption}; template={template:{templateId, locals?}}; reaction={messageId, emoji}; options={title, description?, options:[{label,value?}]}; poll={title, options:[{label,value?}], selectableCount?}; vote={pollMessageId, selectedOptions:[option label(s)]}; location={location:{type:'Point', coordinates:[longitude, latitude]}, text?, address?}; contacts={text?, contacts:[{displayName, phones:[{phone|waId}]}]}; album={items:[{type:'image'|'video', file, text?}] (2-30)}; event={name, startTime(ISO 8601), description?, endTime?, location?, call?}; product={product:{productId, title, currencyCode, priceAmount1000, file}, businessOwnerJid, body?, footer?}; flow={flow:{flowId, text, cta, header?, footer?, screen?, data?, mode?}}. Set viewOnce=true to send image/video/audio as view-once (WhatsApp Web channels; WhatsApp has no view-once documents). Enforces the tenant's monthly messages_out quota before dispatch. Channel-side rejections (WhatsApp 24h window, template required, media too large, etc.) surface as message_send_failed with a details.summary string from the channel — retry with type='template' for WhatsApp re-engagement. album/event/product/ptv/viewOnce dispatch on WhatsApp Web (lancer/evolution) channels only; flow dispatches on WhatsApp Business (Cloud API) channels only.	—

Usage & billing (2)

Tool	Description	Tags
get_mcp_server_stats Get MCP server stats	Reports this server process's tenant-scoped subscription, stream watcher, backpressure, and notification counters. Full description RETURNS a flat object of counters (no arguments). Returns tenant-scoped MCP subscription, stream watcher, backpressure, and notification counters for this server process.	read-onlyidempotent
get_usage Get usage and limits	Returns the tenant's usage snapshot: metered totals, compute breakdown, storage and database bytes, plan limits, and subscription period. Full description RETURNS {period:{granularity, start, end}, meters:{<meter>: number}, computeBreakdown:{<category>: number}, storage:{bytesUsed, filesCount, purposeBytes, categoryBytes, recomputedAt, limitBytes, softThresholdPct}, database:{same shape}, plan:{_id, name, planKey}|null, limits, subscription:{externalId, status, currentPeriodStart, currentPeriodEnd, cancelAtPeriodEnd}|null}. Compare `meters[key]` against `limits` for headroom; `period` is a calendar window (UTC), which is NOT necessarily the subscription period in `subscription`. Returns the tenant's current usage snapshot: billed meter totals (compute_ms, tokens_in/out, stt_ms, transcoding_ms) plus internal counters (messages_in/out), compute breakdown by category, storage + database bytes used, active plan with resolved limits (monthly meter caps, storage/database byte caps, static limits, employee seats), and subscription period info. Defaults to the current calendar month (UTC). Pass granularity: 'day' for today-only totals.	read-onlyidempotent

Custom types (5)

Tool	Description	Tags
create_custom_type Create custom type	Creates a tenant-scoped Custom Type whose field definitions back every ct:<slug> document call afterwards. Full description Creates a new tenant-scoped Custom Type. RETURNS the stored definition plus a 'type' key — the ct:<slug> string you pass to every document tool afterwards. Subsequent calls to create_document('ct:<slug>', ...) will use its field definitions. REMINDER — cel.label / cel.tooltip (on fields, type, tabs, sections) are CEL expressions: quote literals as "'Nome'" or use "t('name')", NOT "Nome". Authoring type-level cel.label REQUIRES cel.preview.lines (pass "preview":null to opt out). Call get_guide('custom-types') for the full DSL. Max 25 types per tenant, 60 fields per type.	—
delete_custom_type Delete custom type	Soft-deletes a Custom Type, along with its existing documents. Full description RETURNS {deleted: true, slug}. Soft-deletes a custom type. Subsequent CRUD calls to ct:<slug> will fail until the type is re-created. Existing docs are also soft-deleted by the afterDelete hook.	destructive
get_custom_type_definition Get custom type definition	Reads a Custom Type's field, tab, section, and CEL definition — the payload you must re-send when updating it. Full description RETURNS {definition} — the fields/tabs/sections/cel definition for a tenant's custom type. Accepts either the raw slug ('leads') or the prefixed form ('ct:leads'). This is the call whose output you must re-send to update_custom_type, because that tool REPLACES the field list rather than merging into it.	read-onlyidempotent
list_custom_types List custom types	Lists the tenant's user-defined Custom Types, so you know which ct:<slug> models exist before using them. Full description Returns the tenant's user-defined Custom Types (ct:<slug>). Use this to discover what tenant-authored models exist before calling create_document/query_documents on a ct:<slug> type.	read-onlyidempotent
update_custom_type Update custom type	Updates a Custom Type's fields, name, CEL, tabs, or sections; the field list is replaced wholesale, not merged. Full description RETURNS the updated definition plus a 'type' key (the ct:<slug> string). Updates fields/name/description/indexedPaths/cel/tabs/sections on an existing custom type. Slug is immutable. DESTRUCTIVE — `patch.fields` REPLACES the entire field list rather than merging into it. To add or change one field you must call get_custom_type_definition first and re-send every existing field alongside your change; any field you omit is deleted, and its data becomes unreachable. The same wholesale-replace applies to indexedPaths, tabs and sections. Same CEL rules as create_custom_type: cel.label / cel.tooltip must be quoted CEL literals or t('key') lookups (not bare display strings); authoring type-level cel.label requires cel.preview.lines (or explicit preview:null).	destructive

Support (6)

Tool	Description	Tags
create_support_ticket Open an AutoTalk support ticket	Files a support ticket with AutoTalk's team on behalf of this tenant, with markdown body and optional attachments. Full description RETURNS the created ticket document, including its `_id` — pass that id to reply_to_support_ticket / resolve_support_ticket / reopen_support_ticket. Files a support ticket with AutoTalk's team on behalf of this tenant. Body is markdown. Attach screenshots or logs via attachments:[{bucket, fullPath}] obtained from begin_file_upload/upload_file_inline. Priority sets the response target (urgent 2h, high 8h, normal 24h, low 72h).	—
get_support_ticket Read one support ticket	Reads one support ticket including its replies — poll it to see whether support has answered. Full description RETURNS the full ticket document including its `replies` array. Poll this to see whether support has answered — tickets have no resource URI, so there is no subscription for them.	read-onlyidempotent
list_support_tickets List this tenant's support tickets	Lists this tenant's own AutoTalk support tickets, newest activity first. Full description RETURNS an array of ticket documents, newest activity first. Lists the tenant's own AutoTalk support tickets.	read-onlyidempotent
reopen_support_ticket Reopen a resolved support ticket	Reopens a resolved support ticket when the problem came back. Full description RETURNS the updated ticket document. Reopens a resolved ticket when the problem came back. Only 'resolved' tickets can be reopened.	idempotent
reply_to_support_ticket Reply on a support ticket	Adds a customer reply to one of this tenant's support tickets and notifies the support team. Full description RETURNS the updated ticket document. Adds a customer reply to one of this tenant's support tickets and notifies the support team. Body is markdown. Replying to a resolved ticket reopens it; closed tickets are terminal — open a new one.	—
resolve_support_ticket Mark a support ticket resolved	Marks one of this tenant's support tickets resolved; replying to it later reopens it. Full description RETURNS the updated ticket document. Marks one of this tenant's tickets resolved because the problem is fixed. Reversible: replying to a resolved ticket reopens it.	idempotent

Schema & references (17)

Tool	Description	Tags
count_documents Count documents	Counts the documents matching a filter in one call — use it whenever the answer is a number. Full description RETURNS {count} — the number of documents matching a filter, in ONE call. USE THIS whenever the answer is a NUMBER: 'how many messages do I have', 'do I have any open conversations', 'quantos canais tenho'. Do NOT call query_documents and count the rows — that pages through the documents themselves and costs many round-trips for a single number. Takes the SAME `type` and `filterTree` grammar as query_documents (see that tool for the filter-tree AST, the per-kind operator allowlist, and the fieldPath rules); it has no sort/skip/limit/fields/expand because none of them change a count. Omit filterTree to count every document of the type that you can see. The count reflects exactly the documents query_documents would return for the same filter — same permissions, same match.	read-onlyidempotent
fetch_user_doc Fetch user doc	Fetches the markdown for one AutoTalk user documentation page, by slug or full URL. Full description RETURNS the page markdown. Get valid slugs from list_user_docs — do not guess them. Fetches the markdown content for a single AutoTalk user-facing documentation page. Accepts a slug (e.g. 'workflows/creating-a-workflow') or full URL. Use list_user_docs to discover available paths.	read-onlyidempotent
generate_document Generate a document	Renders a PDF, DOCX, MD, XLSX, or CSV file server-side from markdown or sheet rows, and stores it. Full description RETURNS {bucket, fullPath, size, contentType, fileName, format} — a storage ref usable with inspect_media, send_message attachments, and document file fields. Renders a document server-side (#185 Layer 2): format 'pdf'/'docx'/'md' from content.markdown (headings, paragraphs, lists, code blocks, simple tables), format 'xlsx'/'csv' from content.sheets ([{name?, rows: string[][]}]; csv uses the first sheet only). Deterministic rendering, not code execution — for computed spreadsheets/charts use the Python workflow action instead. Output capped at 10 MiB; counts toward the tenant's storage quota.	—
get_action_definition Get action definition	Returns one workflow action's full definition — every field, constraint, and output. Full description Returns full action definition with all fields, constraints, and outputs. Use the actionType from list_action_types.	read-onlyidempotent
get_cel_reference Get CEL reference	Returns the CEL variables and functions available in a given context: workflow, agent, or form. Full description Returns available CEL variables and functions for a given context (workflow, agent, or form).	read-onlyidempotent
get_guide Get guide	Returns cookbook-style guides for building workflows and agents, querying data, and sending messages. Full description Returns cookbook-style guides for building workflows, agents, querying data, and sending messages. Call without topic to list available guides. For user-facing product documentation (UI walkthroughs, channels, billing), use list_user_docs / fetch_user_doc instead.	read-onlyidempotent
get_model_definition Get model definition	Returns a dynadata model's field definitions plus its own mcp.tips usage guidance — read it before building a filter tree. Full description RETURNS {name, collectionName, description, fields:[{name, type, description, required, enum, refModel, fields|variants}], functions:{...}, mcp:{tips:[...]}}. The `mcp.tips` array is the model's own usage guidance — which fields express what, which paths are NOT filterable, and worked filter examples; read it before building a filterTree. Returns field definitions for a dynadata model type or embedded definition with descriptions, types, constraints, and nested structure. Supports nested agent/common defs like agents.platform.ActorJson. IMPORTANT: workflows.steps (array), messages.body (discriminated_union), and agents.platform (nested_form) ARE structurally validated by Zod, so validate_document DOES catch wrong shapes there. Only genuinely Mixed fields (schema.type='mixed', compiled to z.any()) accept arbitrary JSON: custom_types.cel, custom_types.calendar, action_tokens.payload, action_tokens.meta, and conversations.agentData.context — plus deep leaf nodes such as step action params and message body variant content/value. Mixed shapes are enforced at render/execute time, not by Zod; check the model's `mcp.tips` and the relevant authoring guide (custom-types.md, docs-reference-cel-editor.md) before authoring such fields.	read-onlyidempotent
get_model_json_schema Get model JSON schema	Returns the Zod-derived JSON Schema for a dynadata model type or embedded definition. Full description Returns the JSON Schema (from Zod) for a dynadata model type or embedded definition. Supports nested agent/common defs like agents.platform.ActorJson.	read-onlyidempotent
get_model_relationships Get model relationships	Returns the relationship graph between dynadata models, showing which fields reference which models. Full description Returns the relationship graph between dynadata models, showing which fields reference which models. Auto-extracted from ref fields in all model definitions.	read-onlyidempotent
get_onboarding_state Get onboarding state	Returns what the account has already set up: onboarding completion, the getting-started checklist, and how many channels and employees exist. Full description RETURNS {startedAt, completedAt, skippedAt, checklist:{<taskKey>:{done,completedAt}}, checklistDismissedAt, channelCount, employeeCount}. Call this FIRST when helping someone set up their account, so you do not re-do work that is already done. `channelCount` counts real (non-test) messaging channels, so 0 means nothing is connected yet.	read-onlyidempotent
list_action_types List action types	Lists every workflow and agent action type by its wire key — the values the docs pages do not print. Full description RETURNS an array of actionType strings — the wire keys, which the docs.autotalk.io action reference pages do NOT print (they use UI labels). Lists all workflow/agent action types. Use get_action_definition for full field details on a specific action.	read-onlyidempotent
list_dynadata_types List dynadata types	Lists the available dynadata model types — the legal values for every `type` argument on this server. Full description RETURNS an array of type names — the legal values for every `type` argument on this server. Lists available dynadata model types. Optionally include embedded agent/common definitions such as agents.platform.ActorJson.	read-onlyidempotent
list_user_docs List user docs	Lists all AutoTalk user documentation pages live from docs.autotalk.io, with slugs, titles, and descriptions. Full description Lists all AutoTalk user-facing documentation pages (UI walkthroughs, channel setup, billing, etc.) live from docs.autotalk.io. Returns slugs + titles + descriptions for each page. Use fetch_user_doc to load the markdown for a specific slug — pass its `locale` when the user writes in Portuguese or Spanish. Titles and descriptions here are always English; the pages themselves are translated.	read-onlyidempotent
search_example_documents Search example documents	Searches AutoTalk's curated example documents for reusable patterns — these are shipped examples, not this tenant's data. Full description RETURNS matching example summaries, or full example documents when includeDocuments is set. These are AutoTalk's shipped EXAMPLES, not this tenant's data — use query_documents for that. Searches curated example dynadata documents to find reusable patterns and optionally return one or many full documents. Do NOT search project files for examples.	read-onlyidempotent
set_onboarding_progress Record onboarding progress	Records a completed getting-started task, or marks onboarding finished. Refuses to declare an account set up while no channel is connected. Full description Marks one getting-started task done, and/or finishes onboarding. Pass `task` after a REAL milestone you just achieved with the user — never speculatively. Pass `complete: true` only when the user says they are done; it is refused while no real channel is connected. RETURNS {updated: [<the onboarding.* leaf paths written>]}. Re-read with get_onboarding_state if you need the new values.	idempotent
upload_file_inline Upload a small file (one step)	Uploads a small file (~1 MB) in a single call by passing its base64 bytes directly — no separate HTTP PUT. Full description Uploads a small file in a single call by passing its base64-encoded bytes directly — no separate HTTP PUT. Returns {bucket, fullPath} suitable for inspect_media or to embed in a document field / send_message. Path and bucket are chosen server-side. Bounded by the MCP request body limit (~1 MB of decoded bytes); for larger files use begin_file_upload + complete_file_upload. Subject to the tenant's storage quota.	—
validate_document Validate document	Validates a document, or specific fields of one, against its model's Zod schema. Full description RETURNS {valid: true} or {valid: false, errors: [...]}. Validates a document against the model's Zod schema. Supports both full documents and partial validation. For large documents (agents, workflows), use the 'fields' parameter to validate only specific top-level fields, or validate fragments directly using embedded types (e.g. type='agents.platform.LlmPlatform'). Returns {valid:true} or {valid:false, errors:[...]}. CAVEAT: A {valid:true} result does NOT guarantee the payload is renderable/executable — fields declared as schema.type='mixed' (Mongoose Mixed) are accepted as opaque JSON. Note that workflows.steps (array), messages.body (discriminated_union), and agents.platform (nested_form) are NOT Mixed — they are structurally validated, so wrong shapes there ARE caught. Genuinely Mixed fields include custom_types.cel, custom_types.calendar, action_tokens.payload, action_tokens.meta, conversations.agentData.context, and message body variant content/value leaves. For those, cross-reference the model's `mcp.tips` plus the authoring guide, or validate the embedded fragment type explicitly (e.g. type='agents.platform.LlmPlatform').	read-onlyidempotent

Usage tips

• The server is self-documenting: call get_guide with no arguments to list its built-in cookbook guides (building-agents, building-workflows, custom-types, querying-data, …) plus offline mirrors of these docs, and read the relevant guide before authoring — e.g. get_guide("custom-types") before creating a Custom Type.
• Start with list_dynadata_types to discover available models, then use get_model_definition for field details.
• Use search_example_documents to find reusable patterns before building agents or workflows from scratch.
• Use validate_document to check your document before creating it with create_document.
• Use test_workflow for rapid iteration — but it is not a dry run: steps read and write your company data exactly as in production, and only the execution record is skipped.
• For large documents, validate specific sections using the fields parameter or embedded types.

Next steps

• API Tokens — Create and manage API tokens
• Webhooks — Configure outgoing event notifications