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 URL https://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/list and 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_details

Get one worker's full configuration: voice/call config (config field), language, phone numbers, active state. 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_details 

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.

destructive idempotent

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.
`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.

destructive idempotent

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_call

Cancel a scheduled outbound call before it goes out.

destructive

Tool name

MCP tool name
 account_admin__cancel_scheduled_call 

Arguments

Name	Type	Required	Description
`call_id`	`string`	yes

MCP tool · account_admin · account_admin

list_recent_calls

List recent phone calls for this account, optionally filtered.

read-only

Tool name

MCP tool name
 account_admin__list_recent_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_call_details

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

read-only

Tool name

MCP tool name
 account_admin__get_call_details 

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, including their tags and linked worker ids. 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: metadata, tags, linked worker ids, and full text content. txt documents read from storage; other types return the processed text (only available once status is "completed"). Long content may be truncated.

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 metadata only.

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. Content updates re-process asynchronously: status returns to 'queued' until embeddings are rebuilt; poll get_document until status is 'completed'.

destructive idempotent

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.
`tag_keys`	`array`		When set, replaces the document's tag set entirely.

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_details

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_details 

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.

destructive idempotent

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_info

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

read-only

Tool name

MCP tool name
 account_admin__get_account_info 