MCP

Model Context Protocol

Connect Claude or your own agent to Threll over MCP. The MCP server exposes admin tools for managing workers, placing confirmed calls, and searching call history conversationally.

BASE URLhttps://mcp.threll.io

MCP

Authentication

The MCP server uses OAuth 2.1 with PKCE. Your client registers, the user approves scopes, and the resulting access token is sent on each tool call.

POST /oauth/register — dynamic client registration
GET /oauth/authorize — user approval
POST /oauth/token — exchange code for access token

MCP

Scopes

Tools are gated by capability scope. The most common scope for integrations is account_admin — covers worker management, call operations, document CRUD, and account info.

Scope	Purpose
`account_admin`	Full Threll admin surface for an account.
`admin`	Worker-scoped admin (configuration only).
`user`	Mid-call worker tools (knowledge base, email, etc.).

MCP

Protocol

Threll's MCP server implements the standard tools/listand tools/call methods. Tool names use the{provider}__{tool} form (e.g. account_admin__list_workers).

MCP tool · account_admin · account_admin

list_workers

List the AI phone workers in this account. A worker's call script/persona is NOT stored on the worker: it comes from documents tagged inbound_call_script or outbound_call_script that are linked to the worker (use list_documents with worker_id). A worker without outbound_phone_number cannot place outbound calls.

read-only

Tool name

MCP tool name
account_admin__list_workers

MCP tool · account_admin · account_admin

get_worker

Get one worker's full configuration: voice/call config (config field, including its own dataRetention policy; null means it follows the account policy, returned as accountDataRetention), language, phone numbers, active state, plus the account's dataRetentionLevel (basic, custom or full) that limits which retention policy update_worker_settings may set. The call script/persona is NOT part of this record — it is stored as tagged documents linked to the worker; use list_documents with worker_id and tag_key, then get_document to read the script.

read-only

Tool name

MCP tool name
account_admin__get_worker

Arguments

Name	Type	Required	Description
`worker_id`	`string`	yes

MCP tool · account_admin · account_admin

update_worker_settings

Update a worker. Only fields you provide are changed; config is shallow-merged (top-level config keys you omit keep their value). The call script text is NOT here — manage it via the document tools. Always confirm with the user before changing voice settings, and before changing config.data_retention, which can permanently remove call data.

destructiveidempotent

Tool name

MCP tool name
account_admin__update_worker_settings

Arguments

Name	Type	Required	Description
`worker_id`	`string`	yes
`name`	`string`
`language`	`string`
`inbound_phone_number`	`string`
`outbound_phone_number`	`string`
`is_active`	`boolean`
`config`	`object`		Call behavior config; shallow-merged — only keys you provide change.

MCP tool · account_admin · account_admin

initiate_phone_call

Place an outbound call. If account.config.require_confirmation_for_outbound_calls is true (the default), this returns a confirmation_required result and you must call confirm_phone_call with the token. Provide call_script_document_ids OR custom_instructions, not both.

destructive

Tool name

MCP tool name
account_admin__initiate_phone_call

Arguments

Name	Type	Required	Description
`worker_id`	`string`	yes
`phone_number`	`string`		E.164 phone number to call. Optional when person_id is set and the person has a stored phone_number.
`person_id`	`string`		ID of a stored person (see list_persons/search_persons). Attaches their profile to the call so the voice agent knows who it is talking to. When set, phone_number may be omitted and defaults to the stored number; an explicit phone_number overrides it.
`context`	`object`		Free-form per-call context (customer details, order info, …). Stored on phone_calls.context.
`context_expires_at`	`string`		ISO 8601 timestamp after which this context is stale. Threll stops carrying it into later inbound calls from this customer once it passes.
`call_script_document_ids`	`array`		UUIDs of documents tagged outbound_call_script. Mutually exclusive with custom_instructions.
`custom_instructions`	`string`		Inline call script. Mutually exclusive with call_script_document_ids.
`customer`	`object`		Customer metadata to attach to the call.
`scheduled_at`	`string`		ISO 8601 future timestamp to schedule the call. Omit for immediate.

MCP tool · account_admin · account_admin

prepare_phone_call

Prepare a single outbound call without placing it. Returns a confirmation_token; the call only goes out when you call confirm_phone_call. Same inputs as initiate_phone_call. Use this even when the account toggle is off if you want explicit human confirmation.

Tool name

MCP tool name
account_admin__prepare_phone_call

Arguments

Name	Type	Required	Description
`worker_id`	`string`	yes
`phone_number`	`string`
`person_id`	`string`		ID of a stored person to attach to the call. When set, phone_number may be omitted and defaults to the stored number.
`context`	`object`
`call_script_document_ids`	`array`
`custom_instructions`	`string`
`customer`	`object`
`scheduled_at`	`string`

MCP tool · account_admin · account_admin

confirm_phone_call

Consume a confirmation_token issued by initiate_phone_call or prepare_phone_call. Atomically transitions the confirmation to consumed and inserts the phone_calls row. The call is then placed (or scheduled).

destructive

Tool name

MCP tool name
account_admin__confirm_phone_call

Arguments

Name	Type	Required	Description
`confirmation_token`	`string`	yes

MCP tool · account_admin · account_admin

prepare_phone_call_batch

Prepare multiple outbound calls in one go (max 100). Returns a single batch_confirmation_token. All calls are validated up front and either all are issued or none. Use confirm_phone_call_batch to enqueue them as scheduled calls.

Tool name

MCP tool name
account_admin__prepare_phone_call_batch

Arguments

Name	Type	Required	Description
`calls`	`array`	yes	Array of call drafts; each entry has the same shape as initiate_phone_call inputs.

MCP tool · account_admin · account_admin

confirm_phone_call_batch

Consume a batch_confirmation_token. Inserts every call as scheduled in one transaction; the existing scheduler dispatches them.

destructive

Tool name

MCP tool name
account_admin__confirm_phone_call_batch

Arguments

Name	Type	Required	Description
`batch_confirmation_token`	`string`	yes

MCP tool · account_admin · account_admin

cancel_pending_confirmation

Revoke a pending confirmation token (single or batch) so it can no longer be consumed.

destructiveidempotent

Tool name

MCP tool name
account_admin__cancel_pending_confirmation

Arguments

Name	Type	Required	Description
`token`	`string`	yes

MCP tool · account_admin · account_admin

cancel_scheduled_phone_call

Cancel a scheduled outbound call before it goes out.

destructive

Tool name

MCP tool name
account_admin__cancel_scheduled_phone_call

Arguments

Name	Type	Required	Description
`call_id`	`string`	yes

MCP tool · account_admin · account_admin

list_recent_phone_calls

List recent phone calls for this account, optionally filtered.

read-only

Tool name

MCP tool name
account_admin__list_recent_phone_calls

Arguments

Name	Type	Description
`worker_id`	`string`
`status`	`string`
`direction`	`string`
`limit`	`integer`	Max results (default 20, max 100).

MCP tool · account_admin · account_admin

search_phone_calls

Search this account's phone calls by phone number, external call ID, or worker.

read-only

Tool name

MCP tool name
account_admin__search_phone_calls

Arguments

Name	Type	Required	Description
`phone_number`	`string`
`external_call_id`	`string`
`worker_id`	`string`
`limit`	`integer`

MCP tool · account_admin · account_admin

get_phone_call

Get full details of a phone call including transcript, events, customer, and config.

read-only

Tool name

MCP tool name
account_admin__get_phone_call

Arguments

Name	Type	Required	Description
`call_id`	`string`	yes

MCP tool · account_admin · account_admin

get_phone_call_analytics

Get phone call analytics for this account: counts by status/direction and average duration. Optional worker and date range filters.

read-only

Tool name

MCP tool name
account_admin__get_phone_call_analytics

Arguments

Name	Type	Required	Description
`worker_id`	`string`
`from_date`	`string`
`to_date`	`string`

MCP tool · account_admin · account_admin

get_outbound_call_policy

Read this account's outbound-call policy: confirmation toggle plus pending confirmations issued by this OAuth client for the calling user.

read-only

Tool name

MCP tool name
account_admin__get_outbound_call_policy

MCP tool · account_admin · account_admin

list_documents

List documents in this account as compact summaries (id, title, type, status, is_active, tag_keys, linked_worker_ids, updated_at). Call scripts are documents tagged inbound_call_script or outbound_call_script and linked to a worker. Documents tagged outbound_call_script can also be referenced per call via initiate_phone_call.

read-only

Tool name

MCP tool name
account_admin__list_documents

Arguments

Name	Type	Required	Description
`worker_id`	`string`		Only documents linked to this worker (or created by it).
`tag_key`	`string`		Only documents with this tag, e.g. inbound_call_script.

MCP tool · account_admin · account_admin

get_document

Get one document's summary and text content. txt and mdoc documents return their exact source text (content_source "file"), readable immediately after an edit; other types return the processed text, only available once status is "completed". Content is returned in windows of up to 50000 characters: when content_truncated is true, call again with offset=next_offset for the rest. To check processing status, pass include_content=false.

read-only

Tool name

MCP tool name
account_admin__get_document

Arguments

Name	Type	Required	Description
`document_id`	`string`	yes
`include_content`	`boolean`		Default true. Set false for the summary only, e.g. when polling status.
`offset`	`integer`		Character offset to start reading from. Default 0.
`limit`	`integer`		Maximum characters to return. Default and maximum 50000.

MCP tool · account_admin · account_admin

create_document

Create a text document in this account. To create a call script for a worker, set worker_id (links the document to the worker — required for the script to be used) and tag_keys: ["inbound_call_script"] for inbound calls or ["outbound_call_script"] for outbound calls. Processing is asynchronous: the document starts in status "queued" and is only used on calls once status is "completed".

Tool name

MCP tool name
account_admin__create_document

Arguments

Name	Type	Required	Description
`title`	`string`	yes
`text`	`string`	yes
`worker_id`	`string`		Links the document to this worker. Required for call scripts: a worker only uses scripts linked to it.
`tag_keys`	`array`		Tag keys controlling how the document is used. Call scripts: inbound_call_script / outbound_call_script.

MCP tool · account_admin · account_admin

update_document

Update a document's title, active state, tags, or (txt and mdoc documents only) its full text content. To change part of the text, use edit_document instead of resending the whole content. Content updates re-process asynchronously: status returns to 'queued' until embeddings are rebuilt; poll get_document with include_content=false until status is 'completed'.

destructiveidempotent

Tool name

MCP tool name
account_admin__update_document

Arguments

Name	Type	Required	Description
`document_id`	`string`	yes
`title`	`string`
`is_active`	`boolean`
`text`	`string`		Replace the full text content (txt and mdoc documents only). Triggers async re-processing. Never send content read with content_truncated=true: the unread remainder would be lost.
`tag_keys`	`array`		When set, replaces the document's tag set entirely.

MCP tool · account_admin · account_admin

edit_document

Change part of a txt or mdoc document's text without resending all of it. Each edit replaces old_text with new_text in the stored source; edits apply in order, and each sees the result of the previous one. old_text must match the source exactly (whitespace included) and occur exactly once unless replace_all is true; otherwise nothing is changed and the error says which edit failed. Content changes re-process asynchronously like update_document.

destructive

Tool name

MCP tool name
account_admin__edit_document

Arguments

Name	Type	Required	Description
`document_id`	`string`	yes
`edits`	`array`	yes	1 to 50 replacements, applied in order.

MCP tool · account_admin · account_admin

delete_document

Delete a document. If it is an active call script, the worker loses that script — prefer update_document with is_active=false to take a script out of use reversibly.

destructive

Tool name

MCP tool name
account_admin__delete_document

Arguments

Name	Type	Required	Description
`document_id`	`string`	yes

MCP tool · account_admin · account_admin

list_persons

List this account's persons (leads, customers, phone contacts), optionally filtered by type or worker. Use person_id with initiate_phone_call / prepare_phone_call to attach a profile to an outbound call.

read-only

Tool name

MCP tool name
account_admin__list_persons

Arguments

Name	Type	Description
`type`	`string`
`worker_id`	`string`
`limit`	`integer`	Max results (default 20, max 100).
`offset`	`integer`

MCP tool · account_admin · account_admin

search_persons

Search this account's persons by free text (name, email, phone, company) or exact phone number, email, or external_id. Use this before create_person to avoid duplicates.

read-only

Tool name

MCP tool name
account_admin__search_persons

Arguments

Name	Type	Description
`query`	`string`	Free-text search across first name, last name, email, phone number, and company.
`phone_number`	`string`
`email`	`string`
`external_id`	`string`
`type`	`string`
`limit`	`integer`

MCP tool · account_admin · account_admin

get_person

Get the full profile of one person, including contact details, address, tags, and notes.

read-only

Tool name

MCP tool name
account_admin__get_person

Arguments

Name	Type	Required	Description
`person_id`	`string`	yes

MCP tool · account_admin · account_admin

create_person

Create a person (lead, customer, or phone contact) in this account. Search first with search_persons to avoid duplicates.

Tool name

MCP tool name
account_admin__create_person

Arguments

Name	Type	Required	Description
`type`	`string`	yes	Person kind. 'lead' and 'customer' are contacts the AI calls or recognizes on inbound calls. 'phone_contact' with a worker_id makes the person available as a call-transfer/email contact during that worker's voice sessions.
`first_name`	`string`	yes
`last_name`	`string`	yes
`external_id`	`string`		Identifier in an external system (e.g. your CRM). Must be unique within the account.
`email`	`string`
`phone_number`	`string`		E.164 format, e.g. +4712345678. Inbound calls auto-match persons by this number; keep it E.164.
`language`	`string`
`company_name`	`string`
`city`	`string`
`country`	`string`
`postal_code`	`string`
`street_address`	`string`
`state_or_province`	`string`
`job_title`	`string`
`facebook_url`	`string`
`website_url`	`string`
`linked_in_url`	`string`
`notes`	`string`
`tags`	`array`		Tag strings for categorizing and filtering persons.
`worker_id`	`string`		Optional worker to attach this person to. Required for type phone_contact to surface as a transfer/email contact.

MCP tool · account_admin · account_admin

create_persons_batch

Create multiple persons in one go (max 100), e.g. to import a lead list. All entries are validated up front and either all are created or none.

Tool name

MCP tool name
account_admin__create_persons_batch

Arguments

Name	Type	Required	Description
`persons`	`array`	yes	Array of persons; each entry has the same shape as create_person inputs.

MCP tool · account_admin · account_admin

update_person

Update a person. Only fields you provide are changed.

destructiveidempotent

Tool name

MCP tool name
account_admin__update_person

Arguments

Name	Type	Required	Description
`person_id`	`string`	yes
`type`	`string`		Person kind. 'lead' and 'customer' are contacts the AI calls or recognizes on inbound calls. 'phone_contact' with a worker_id makes the person available as a call-transfer/email contact during that worker's voice sessions.
`first_name`	`string`
`last_name`	`string`
`external_id`	`string`		Identifier in an external system (e.g. your CRM). Must be unique within the account.
`email`	`string`
`phone_number`	`string`		E.164 format, e.g. +4712345678. Inbound calls auto-match persons by this number; keep it E.164.
`language`	`string`
`company_name`	`string`
`city`	`string`
`country`	`string`
`postal_code`	`string`
`street_address`	`string`
`state_or_province`	`string`
`job_title`	`string`
`facebook_url`	`string`
`website_url`	`string`
`linked_in_url`	`string`
`notes`	`string`
`tags`	`array`		Tag strings for categorizing and filtering persons.
`worker_id`	`string`		Optional worker to attach this person to. Required for type phone_contact to surface as a transfer/email contact.

MCP tool · account_admin · account_admin

delete_person

Delete a person. Their phone call history is kept; the calls just lose the person link. Confirm with the user before deleting.

destructive

Tool name

MCP tool name
account_admin__delete_person

Arguments

Name	Type	Required	Description
`person_id`	`string`	yes

MCP tool · account_admin · account_admin

get_telephony_status

Per worker: has outbound number, has inbound number, telephony provider. Use this to check whether the account can make calls before calling initiate_phone_call.

read-only

Tool name

MCP tool name
account_admin__get_telephony_status

MCP tool · account_admin · account_admin

list_integrations

List all integration types and whether this account has each one configured. Never returns decrypted credentials.

read-only

Tool name

MCP tool name
account_admin__list_integrations

MCP tool · account_admin · account_admin

get_account

Get this account's basic info, memberships, and webhook config status (no secrets).

read-only

Tool name

MCP tool name
account_admin__get_account