MCP tools

The MCP server provides read tools for agents, sources, conversations, contacts, teams, analytics, and organizations. It also provides write tools for creation, restoration, updates, tests, deletion, and organization switching.

Read access is intentionally narrower than write access. Treat tools that delete, update, or test an agent as actions with consequences. The client can invoke them in a single step. A test creates an mcp_test conversation and spends model credits. improve_answer is also flagged destructive: it upserts a QnA source by originating message, so a second call for the same message replaces the pair that the first call wrote.

The server also provides ticket tools for the Help Desk inbox: list and inspect tickets and their message threads, assign a ticket, change its status, add an internal note, and close it. find_tickets finds a ticket by text, customer email, or chat session, and list_email_deliveries shows what SendGrid did with each outbound email on a ticket. list_tickets with view: "my_teams" lists the tickets on the teams that you are a member of. A teamId narrows the list to one of your own teams. It never adds a team that you are not on, so a caller on no team gets an empty page. view: "undelivered" lists every ticket whose reply could not reach the customer. Each row's undeliveredReason is the stored reason that the fallback path refused. It is null when no refusal is stored. An undelivered ticket can also have null: its fallback attempts ran out, or it has no fallback email thread. reply_to_ticket sends a real, customer-facing message and is gated on the separate mcp:send scope described in MCP scopes — holding mcp:write alone does not authorize it.

To send a file with a reply, upload it first with upload_attachment, then pass the uploadId it returns in reply_to_ticket's attachmentUploadIds. The tool takes the ticketId the reply is for, and the same mcp:send scope and Standard plan as reply_to_ticket. Give exactly one of two shapes. {filename, contentType, dataBase64} carries the bytes inline, at most 10 MB once decoded. {sourceUrl, filename?} names an https URL that the server fetches, at most 25 MB. The server refuses a URL that resolves to a private, loopback, link-local or other internal address, re-checks every redirect, and follows at most three. The allowed types are the ones the Inbox composer allows: images except SVG, plain text, and PDF. A file that says it is a PNG, JPEG, WebP or GIF must really be one. A widget or email customer sees those four image types inline; every other file reaches the customer as a link. Each upload id works for one message only, and an upload the tool refuses returns ATTACHMENT_TYPE_NOT_ALLOWED, ATTACHMENT_TOO_LARGE, ATTACHMENT_SOURCE_INVALID, ATTACHMENT_SOURCE_BLOCKED or ATTACHMENT_FETCH_FAILED.

Organization-administration tools cover API keys and membership: list_api_keys and revoke_api_key, and list_members and list_invitations. These require the mcp:admin scope. Billing data (subscription, usage, credit history, and plan limits) is reachable through the catalog under the mcp:billing scope rather than as dedicated tools. See MCP scopes for how a client requests each of these narrower scopes.

Dedicated tools cover the most common work, but they do not cover every REST API v1 operation. Five catalog tools reach the remainder by operation id. These are AgentStack API operations, not the Actions that you configure on an agent. search_api_actions runs a full-text search over every AgentStack API operation and returns up to ten ids with their summaries. get_api_action_details returns the input and output JSON Schema for one id. execute_read_action, execute_write_action, and execute_delete_action then call that operation with the arguments the schema describes. Each executor accepts only operations of its own effect and rejects the others, so a destructive call always reaches the tool that a client prompts to confirm.

Call search_api_actions first, then get_api_action_details, and only then an executor. The executors take arbitrary arguments, and the schema is how a client learns their shape. The catalog does not widen access. On a connection that selects toolsets, the catalog reaches only those toolsets: an executor refuses an operation outside the selection with the error code OUT_OF_TOOLSET_PARTITION. search_api_actions does not apply the selection, so it can return an id that the executors then refuse. See MCP server for the toolset names. An operation that your role cannot reach is absent from search results and from the details tool, and the executors re-check permission and scope against the target operation. An operation that your plan, role, or token scope does not currently allow is listed with available: false and a reason, rather than hidden. The executors themselves carry no fixed scope, so a narrowly scoped token still reaches exactly the operations that its own scope covers.

MCP sources support url and text. URL indexing is asynchronous. When you create a source, the response shows its indexing state and next action. You can then poll get_source until the status is ready or failed. Both are terminal. indexing means poll again. You can restore a soft-deleted agent or source only within the 30-day window.

Optional include fields expose extra detail for an agent, a source, or a conversation. If a workflow needs that detail, request the include fields. get_agent with include: ["channels"] also returns the voice call settings of the agent. These settings are read-only. You enable or change voice calls in the dashboard only.

list_models lists every model that an agent can use, with the credits that one reply costs and whether your plan permits it. Pass its id as model to create_agent or update_agent. list_answer_gaps lists the replies of an agent that went wrong: low confidence, no match, a failed search, an escalation, or a thumbs-down. get_answer_trace shows the sources and scores behind one of those replies. All three are read tools under mcp:read and spend no credits.

list_webhook_endpoints lists the webhook endpoints of an agent, and list_webhook_attempts lists the recent delivery attempts: the endpoint, event type, the HTTP status that the endpoint answered, the outcome, and the time. Neither tool returns a payload body. Pass an endpointId from list_webhook_endpoints to read and page one endpoint. Without it, you get the newest attempts across the endpoints of the agent, with no next page when it has two or more. Both are read tools under mcp:read that spend no credits, and both need an admin role, like the webhook portal URL.

A customer who emails your agent can attach a file. Each message that get_conversation returns carries an attachments array, and each entry names the file, its content type, its size and its own id. Pass that id to get_message_attachment, a read tool under mcp:read, to read the text the platform extracted from the file when it arrived. The tool is text-only: it does not return the file's bytes. Cap the text with maxTextChars before you pass the result to a model. An entry with available: false records a file the platform could not store, and an entry with hasText: false names a file with no extractable text, such as an archive. See REST API: conversations for the same data over REST.

Three tools cover background contacts exports. start_contacts_export, a write tool under mcp:write, starts a CSV export of the contacts that match its filters and returns the export id with the status pending. Only one contacts export runs in an organization at a time, so a second call answers a conflict until the first one finishes. get_contacts_export and list_contacts_exports are read tools under mcp:read. They return each export's status (pending, processing, completed, failed, or expired), its filters, size, error message, and expiry. When an export is completed and not expired, the result has a downloadUrl: a presigned link to the CSV that works for up to 1 hour. Each call mints a new link. The file itself stays available for 7 days after the export completes. All three tools need the Contacts export permission. See REST API: contacts for the same exports over REST.

The operation sources.pages.delete, reached through execute_delete_action, deletes one page of a crawled website. The delete sticks: later crawls, manual and automatic retrains, and a website restore skip that URL. The operation sources.pages.restore, reached through execute_write_action, undoes the delete and queues a crawl of that one page. Find both with search_api_actions. They behave the same as the REST endpoints in REST API: sources and ingestion.

The server resolves the active organization in this order:

1. The MCP organization that you pin manually.
2. The active dashboard organization.
3. The oldest membership.

switch_organization persists the selection.

Tool responses echo the organization identity. Before you apply a mutation, check this identity for an unexpected context.

A tool that writes data also gets server-side duplicate removal. If a client calls the same tool twice with the same arguments in a short window, the second call returns the result of the first, with deduped: true added to the payload. reply_to_ticket sends a real message, so it uses a longer window and refuses the call when it cannot confirm the state. See Pagination and errors for the windows and the two error codes.

Changes

• 2026-10-20 — New tools start_contacts_export (mcp:write), list_contacts_exports, and get_contacts_export (mcp:read) for background contacts exports. A completed export carries a 1-hour downloadUrl, and its file stays available for 7 days.
• 2026-10-20 — New tool upload_attachment (scope mcp:send) uploads a file for a ticket reply from base64 or an https URL and returns an uploadId for reply_to_ticket.
• 2026-10-11 — sources.pages.delete sticks: crawls and retrains no longer index the deleted page again. New operation sources.pages.restore undoes the delete and crawls the page again. Reach both through the catalog tools.
• 2026-09-24 — Source status is one of indexing, ready, or failed on get_source, create_source, and restore_source. list_sources can also return deleted. ready and failed are terminal, so stop polling on either. indexing means poll again. Before this change, a website or file source showed the raw pipeline word and never reached ready.
• 2026-09-24 — The get_conversation description names its include values: messages, metadata, and feedback.
• 2026-09-24 — The descriptions of the five catalog tools say that they reach AgentStack API operations. They do not reach the Actions that you configure on an agent. The tool names did not change.
• 2026-09-24 — list_tickets with view: "my_teams" uses the teams that you are a member of. Before this change, it returned an empty page unless you gave a teamId, and then it returned that team even if you were not on it. A teamId now narrows the list to one of your own teams.
• 2026-09-24 — list_tickets accepts view: "undelivered", and each row has an undeliveredReason field.
• 2026-09-24 — New read tools find_tickets and list_email_deliveries, under the mcp:read scope. Both need the Standard plan, like the other ticket tools.
• 2026-09-24 — New read tools list_models, list_answer_gaps, and get_answer_trace, under the mcp:read scope. They spend no credits.
• 2026-09-24 — get_agent with include: ["channels"] returns a read-only voice object next to email, slack, and widget.
• 2026-09-24 — The MODEL_NOT_SUPPORTED error of create_agent and update_agent ends with Call list_models for valid ids.
• 2026-09-24 — New read tools list_webhook_endpoints and list_webhook_attempts, under the mcp:read scope. They need an admin role and spend no credits. They never return a payload body.