MCP tool reference - SiteGPT Docs

This page describes the tools of the remote SiteGPT MCP server at https://sitegpt.ai/mcp. To connect an app, see Connect an AI assistant with MCP. The local server (sitegpt mcp) has other tools. See Local server tools.

Connection

Item	Value
Endpoint	`https://sitegpt.ai/mcp`
Transport	Streamable HTTP
Authentication	OAuth, with approval in the browser. An API token (`sgpt_...`) also works as a bearer token. See Authentication.
Plan	Growth plan and above. See Plans and limits. On a lower plan, calls fail with `403 PLAN_UPGRADE_REQUIRED`.
Sign-in needed	Yes, for every tool. A request without a credential gets `401 AUTHORIZATION_HEADER_REQUIRED`.

Scopes

The app can ask for any scope in the scope table. If the app asks for no scopes, SiteGPT asks for the Standard access level: every scope except creating or changing tokens (tokens:write), changing billing (billing:write), and reading or changing integrations (integrations:read, integrations:write).
The connection gets only the scopes that your dashboard role allows on the chatbots that you select on the approval page.
Read only on the approval page keeps only the requested scopes that end in :read. See Connect with read-only access.
With an API token as the bearer, the token’s own scopes and chatbot access apply.
An access token is valid for 1 hour. The app gets a new one with its refresh token, which is valid for 90 days.

Each tool checks the scopes of the API v2 operations that it calls. A call without a needed scope fails with 403 TOKEN_SCOPE_NOT_ALLOWED, and details.requiredScopes lists the missing scopes. A scope alone is not enough: your role must also allow the action on that chatbot.

Tool summary

Access type puts each tool in one class:

Read: the tool gets data. It does not change data, account state, or permissions.
Write: the tool creates, changes, or deletes data, or changes settings.
Sensitive write: the tool sends a message to another person, or it can delete data that cannot be restored. reply_to_conversation sends a message to a real website visitor and can take over the conversation. execute_write can delete data that cannot be restored, invite members by email, reply to visitors, and send email drafts to customers.

Access type is a documentation class. SiteGPT does not send it to the app. Ask the user to approve each Sensitive write call. The columns Read only, Destructive, Idempotent, and Open world show the MCP tool annotations that SiteGPT sends to the app (readOnlyHint, destructiveHint, idempotentHint, openWorldHint).

Tool	Access type	Read only	Destructive	Idempotent	Open world	Scopes	Personal data
`search`	Read	Yes	No	Yes	No	None	No
`execute_read`	Read	Yes	No	Yes	No	Those of the `GET` operation called	Depends on the operation
`execute_write`	Sensitive write	No	Yes	No	Yes	Those of the operation called	Depends on the operation
`preview_chatbot`	Read	Yes	No	Yes	No	None	No
`send_chat_message`	Write	No	No	No	Yes	`conversations:write`	Message text
`get_onboarding_status`	Read	Yes	No	Yes	No	`account:read`	No
`get_chatbot_appearance`	Read	Yes	No	Yes	No	`settings:read`, `starters:read`	No
`update_chatbot_appearance`	Write	No	Yes	Yes	Yes	`settings:write`	No
`list_conversations`	Read	Yes	No	Yes	No	`conversations:read`	Visitor name, email, messages, page URL
`get_conversation`	Read	Yes	No	Yes	No	`conversations:read`	Visitor name, email, transcript, page URL
`reply_to_conversation`	Sensitive write	No	No	No	Yes	`conversations:write`	Reply text to a visitor
`get_chatbot_analytics`	Read	Yes	No	Yes	No	`chatbots:read`, `account:read`	No (counts only)
`list_leads`	Read	Yes	No	Yes	No	`leads:read`	Lead name, email, phone
`list_escalations`	Read	Yes	No	Yes	No	`conversations:read`	Visitor name, email, messages, page URL
`list_knowledge_sources`	Read	Yes	No	Yes	No	`knowledge:read`	No
`create_knowledge_source`	Write	No	No	No	Yes	`knowledge:write`	No
`authorize_knowledge_source`	Write	No	No	Yes	Yes	`knowledge:write`	No
`upload_knowledge_file`	Write	No	No	No	Yes	`knowledge:write`	File content
`open_sitegpt`	Read	Yes	No	Yes	No	`chatbots:read`	No
`open_sitegpt_inbox`	Read	Yes	No	Yes	No	`chatbots:read`	No
`read_sitegpt_settings`	Read	Yes	No	Yes	No	`chatbots:read`, `settings:read`	No
`update_sitegpt_settings`	Write	No	Yes	Yes	Yes	`settings:write`, `settings:read`, `chatbots:read`	No

ChatGPT and Codex do not get get_onboarding_status, and the remote server refuses onboarding API calls from them with NOT_AVAILABLE_IN_THIS_ASSISTANT. They also cannot read /api/v2/openapi.json with execute_read. That call returns 403 USE_SEARCH_TOOL. Use search instead. In a HIPAA workspace, the tools that return conversations, leads, or escalations are blocked.

Code tools

search, execute_read, and execute_write take one input, code: a JavaScript async arrow function as a string. The code runs on SiteGPT’s side and can call API v2 only. The result is the return value of the function, as text in result.

Tool	What the code can do	Side effects
`search`	Search the API v2 specification to find an operation. It makes no API calls.	None
`execute_read`	Call API v2 operations with `GET` only. Other methods fail with “Method … is not allowed in execute_read”.	None
`execute_write`	Call API v2 operations with `POST`, `PUT`, `PATCH`, or `DELETE`.	Any change that API v2 allows, including deletes. Deletes need confirmation. See Deletes need confirmation.

The scopes, inputs, outputs, and errors of each operation are in the API reference.
An API error does not end the tool call. It comes back inside result as {"ok": false, "error": {"code": "...", "message": "..."}}.
execute_write cannot create or change GitHub sources, because they carry an access token. Connect GitHub in the dashboard. See Connect GitHub.
The code stops after 20 seconds.

Chatbot and conversation tools

preview_chatbot

Shows a live preview of a chatbot widget.

Input	Type	Required	Notes
`chatbotId`	string	Yes	The chatbot ID.
`title`	string	No	A title for the preview. Up to 200 characters are used.

Returns: chatbotId, widgetUrl, and title. Apps that support MCP app views show the preview. Side effects: None. A preview does not count in analytics. Errors: A value that is not a chatbot ID returns an error. The tool does not check that the chatbot exists.

send_chat_message

Sends a message to a chatbot as a visitor and returns the answer.

Input	Type	Required	Notes
`chatbotId`	string	Yes	The chatbot ID.
`message`	string	Yes	1 to 20,000 characters.
`threadId`	string	No	Continue this conversation. Leave it out to start a new conversation.

Returns: chatbotId, threadId, answer, and messageType. If the chatbot is in Human mode, answer is null, because the chatbot does not reply. If the message gets your away message outside working hours, the text result includes the away message. Side effects:

Creates a real conversation, or adds a message to one.
An AI answer counts toward your message quota. See Plans and limits.
The AI can escalate the conversation to your team.

Errors: 403 ACCOUNT_INACTIVE (the chatbot owner has no active plan), 404 CONVERSATION_NOT_FOUND, 409 CONVERSATION_CLOSED (the conversation is resolved), 429 MESSAGE_LIMIT_REACHED (the conversation reached its message limit, so leave out threadId to start a new conversation), 400 VALIDATION_FAILED.

list_conversations

Lists the conversations of a chatbot.

Input	Type	Required	Notes
`chatbotId`	string	Yes	The chatbot ID.
`status`	string	No	`all` (default), `open`, or `resolved`.
`escalated`	boolean	No	Only escalated, or only not escalated, conversations.
`limit`	integer	No	1 to 100. The default is 50.
`cursor`	string	No	The `nextCursor` from the last page.

Returns: conversations and nextCursor. Each conversation has threadId, title, mode, escalated, resolved, important, startedAt, updatedAt, totalMessages, unreadMessages, visitor (name, email), pageUrl, lastMessage, lastQuestion, lastAnswer, and lastFrom (visitor, bot, or agent). If the last message is your away message, lastFrom is visitor, because the visitor still waits for your team. Message text is cut to 200 characters. Side effects: None. Errors: 400 VALIDATION_FAILED for a filter that is not valid.

get_conversation

Reads the transcript of one conversation.

Input	Type	Required	Notes
`chatbotId`	string	Yes	The chatbot ID.
`threadId`	string	Yes	The conversation ID.

Returns: threadId, title, mode, escalated, resolved, important, startedAt, visitor, pageUrl, lastFrom, dashboardUrl (the conversation in the dashboard), and messages. Each message has messageId, question, answer, messageType, systemMessageType, and createdAt. The tool returns the last 200 messages, with each text cut to 2,000 characters. It does not return lead form answers. If the last message is your away message, lastFrom is visitor, because the visitor still waits for your team. Side effects: None. Errors: 404 CONVERSATION_NOT_FOUND.

reply_to_conversation

Sends a reply to the visitor as a person on your team.

Input	Type	Required	Notes
`chatbotId`	string	Yes	The chatbot ID.
`threadId`	string	Yes	The conversation ID.
`message`	string	Yes	1 to 20,000 characters.

Returns: threadId, reply (messageId, text, createdAt), tookOver, and delivery (channel, delivered, reason). Side effects:

The visitor sees the reply in the chat widget, on WhatsApp or Messenger for a conversation there, or by email for an email conversation. See Email.
If your team does not handle the conversation yet, the reply takes it over first: the AI stops answering, and the visitor sees that a human agent joined. tookOver is then true. See Reply to visitors and take over.
Except in a WhatsApp, Messenger, or email conversation, SiteGPT can email the reply to the visitor, the same as a reply from Chat History. See When SiteGPT emails your reply to the visitor.
Each call sends another message.

Status: If a WhatsApp message cannot be delivered, delivery.delivered is false and delivery.reason tells why. For example, over_quota means that the WhatsApp add-on does not cover this number, and disconnected means that the number is no longer connected. See If a number is not covered. For an email conversation, delivery.channel is email. If the email cannot go out, delivery.reason is hipaa_blocked, unentitled (the AI Email Support add-on does not cover the inbox), no_inbox (the inbox was removed), or send_failed (the inbox is still being set up, or the email could not be sent). The reply stays in the conversation. For a Messenger conversation, delivery.channel is messenger. If Messenger does not deliver the reply, delivery.reason is outside_window (Meta’s time limit passed, see Messenger), disconnected (the Facebook Page is no longer connected), hipaa_blocked, or send_failed. The reply stays in the conversation. Errors: 409 CONVERSATION_CLOSED (the conversation is resolved), 409 REPLY_IN_CHANNEL (the conversation is on Slack, Crisp, or another channel with its own agent inbox, so reply there), 404 CONVERSATION_NOT_FOUND, 503 REPLY_NOT_SENT, 400 VALIDATION_FAILED.

list_escalations

Lists escalated conversations that are still open and wait for your team.

Input	Type	Required	Notes
`chatbotId`	string	Yes	The chatbot ID.
`limit`	integer	No	1 to 100. The default is 50.
`cursor`	string	No	The `nextCursor` from the last page.

Returns: escalations and nextCursor. Each escalation has the same fields as a conversation in list_conversations. Side effects: None.

list_leads

Lists the leads of a chatbot.

Input	Type	Required	Notes
`chatbotId`	string	Yes	The chatbot ID.
`status`	string	No	`all` (default), `open`, or `archived`.
`query`	string	No	Searches name, email, and phone. Up to 200 characters.
`limit`	integer	No	1 to 100. The default is 50.
`cursor`	string	No	The `nextCursor` from the last page.

Returns: leads and nextCursor. Each lead has id, name, email, phone, important, archived, and createdAt. Side effects: None. Errors: 400 VALIDATION_FAILED.

get_chatbot_analytics

Reads the analytics of a chatbot.

Input	Type	Required	Notes
`chatbotId`	string	Yes	The chatbot ID.

Returns:

conversations: message count and the share of positive and negative feedback.
training: the training state and the counts of trained, pending, and failed documents.
knowledge: the counts of pages, documents, links, and files.
quota: messages, pages, and chatbots used and allowed, and the current usage window.
history: the last 12 months.
engagement: totals for the last 30 days, with a comparison to the 30 days before. It is null when your plan does not include analytics.

Side effects: None.

Appearance and settings tools

get_chatbot_appearance

Reads how the chat widget looks.

Input	Type	Required	Notes
`chatbotId`	string	Yes	The chatbot ID.

Returns: appearance (title, tooltip, welcomeMessage, placeholderText, brandColor, brandTextColor, iconBackgroundColor, linkColor, iconPosition, iconShape, enableDarkMode) and the first 8 conversation starters (id, title). Side effects: None.

update_chatbot_appearance

Changes how the chat widget looks. Give at least one field to change.

Input	Type	Required	Notes
`chatbotId`	string	Yes	The chatbot ID.
`title`	string	No	1 to 120 characters.
`welcomeMessage`	string	No	Up to 2,000 characters.
`placeholderText`	string	No	Up to 500 characters.
`tooltip`	string	No	Up to 500 characters.
`brandColor`, `brandTextColor`, `iconBackgroundColor`, `linkColor`	string	No	A hex color, for example `#1a73e8`.
`iconPosition`	string	No	`LEFT` or `RIGHT`.

Returns: chatbotId and the saved appearance. Side effects: The widget on your website changes at once. Errors: 400 VALIDATION_FAILED.

read_sitegpt_settings

Reads four settings: lead email notifications, human handoff, how new conversations start, and hide sources in answers. It takes no input. It reads up to 10 chatbots: the first 10 in your chatbot list, which are the chatbots that you were added to most recently. To change a setting of another chatbot, use the dashboard or execute_write. Returns: schema, values, and layout. Each setting is named <field>__<chatbotId>, where <field> is leadEmails, humanSupport, chatMode, or hideSources. chatMode is WORKING_HOURS while the chatbot follows its working hours, and VISITOR_CHOICE while Let the Visitor Choose is selected. Visitors get the question only while humanSupport is true. Otherwise it is the fixed chat mode, AI or AGENT. A setting that your role cannot read is left out. Side effects: None.

update_sitegpt_settings

Changes the settings that read_sitegpt_settings returns.

Input	Type	Required	Notes
`set`	object	Yes	Setting names from `read_sitegpt_settings` and their new values. `chatMode` takes `AI`, `AGENT`, `WORKING_HOURS`, or `VISITOR_CHOICE`. The other settings take `true` or `false`.

SiteGPT checks every value before it saves any change. Each change goes through the same checks as the dashboard. Returns: values, read again after the save. Side effects: The changes are live at once. For example, chatMode set to AGENT sends every new conversation to your team, and the AI does not answer first. Setting chatMode to AI or AGENT turns working hours and visitor choice off. SiteGPT keeps the schedule and the visitor choice text. WORKING_HOURS turns the saved schedule on again and turns visitor choice off. It does not change the fixed chat mode that Zendesk and Zoho SalesIQ use. To create or change the schedule, use the dashboard or API v2. VISITOR_CHOICE turns visitor choice on with the saved question and button labels, or with the default text if none are saved, and turns working hours off. Visitors get the question only while humanSupport is true. Otherwise new conversations start with the AI. A saved schedule stays and then decides what a visitor who asks for a person gets. See Connect visitors to your team during your hours. To change the question or the labels, use the dashboard or API v2. Errors: An unknown setting name or a value that is not valid fails before anything is saved. WORKING_HOURS for a chatbot without saved working hours also fails before anything is saved, with “This chatbot has no working hours yet. Set them on the Chat Modes page of the SiteGPT dashboard first.” If SiteGPT refuses a change partway, the error tells how many changes it saved before it stopped.

Content tools

list_knowledge_sources

Lists the connected sources of a chatbot and the training state of its documents.

Input	Type	Required	Notes
`chatbotId`	string	Yes	The chatbot ID.

Returns:

sources: each with id, name, connector, status (PENDING, ACTIVE, FAILED, or REVOKED), statusReason, hasCredentials, and createdAt.
documents: document counts by status and by source. The document statuses are BACKLOG, QUEUED, PROCESSING, SUCCESS, FAILED, CANCELLED, and BLOCKED_BY_QUOTA.

Side effects: None. Status: Use this tool to follow training after upload_knowledge_file or a new source. Documents move from QUEUED and PROCESSING to SUCCESS or FAILED.

create_knowledge_source

Connects a new source from another app.

Input	Type	Required	Notes
`chatbotId`	string	Yes	The chatbot ID.
`connector`	string	Yes	`NOTION`, `GOOGLE_DRIVE`, `DROPBOX`, `ONEDRIVE`, `BOX`, `SHAREPOINT`, or `CONFLUENCE`.
`name`	string	Yes	1 to 120 characters.
`domain`	string	For Confluence	Your Confluence domain.

Returns: source, authorizationUrl, and nextStep. Side effects: Creates the source with the status PENDING. Status: The source stays PENDING until you open authorizationUrl and sign in to the other app in your browser. Errors: 400 CONNECTOR_REQUIRED, 400 CONFLUENCE_DOMAIN_REQUIRED, 403 HIPAA_CONNECTORS_DISABLED (a HIPAA workspace), 503 HIPAA_CHECK_UNAVAILABLE.

authorize_knowledge_source

Gets a new authorization link for a source.

Input	Type	Required	Notes
`chatbotId`	string	Yes	The chatbot ID.
`connectionId`	string	Yes	The source `id` from `list_knowledge_sources`.

Returns: The same fields as create_knowledge_source. Side effects: Sets a new authorization link for the source. Errors: The same as create_knowledge_source.

upload_knowledge_file

Uploads one file as content.

Input	Type	Required	Notes
`chatbotId`	string	Yes	The chatbot ID.
`name`	string	Yes	The file name, 1 to 255 characters.
`type`	string	No	The MIME type. The default is `application/octet-stream`.
`base64`	string	Yes	The file content in base64. The file can be up to 1.5 MB. For a larger file, use the dashboard.

Returns: fileName, documentsCount, and ingestJobRunIds. Side effects:

The file is added to the chatbot’s content and uses pages of your plan.
After training, the chatbot uses the file in its answers.

Status: The upload returns before training ends. Check training with list_knowledge_sources. Errors: 429 CHATBOT_PAGES_LIMIT_REACHED (no pages left), 413 FILE_TOO_LARGE, 400 FILE_BASE64_NOT_VALID, 503 HIPAA_UPLOADS_BLOCKED, 400 HIPAA_TXT_ONLY, 502 KNOWLEDGE_INGEST_FAILED.

Home view tools

open_sitegpt and open_sitegpt_inbox

Open the SiteGPT home view, with a chatbot switcher and the tabs Inbox, Escalations, Leads, Analytics, and Knowledge. open_sitegpt_inbox is named Support Inbox and opens the view as a panel inside a conversation, in apps that support panels. In those apps, the conversation or lead that you open becomes context for that chat. Both tools take no input. Returns: chatbots (id, title) and truncated. The switcher lists up to 1,000 chatbots. truncated is true when you have more. A connection limited to some chatbots lists only those. Side effects: None by itself. In the views, the reply form calls reply_to_conversation, and the Knowledge tab can connect an app (Connect, Connect again) and upload a file (Upload and train) with create_knowledge_source, authorize_knowledge_source, and upload_knowledge_file. These calls have the side effects of those tools.

Onboarding tool

get_onboarding_status

Shows the setup status of a temporary chatbot from agent-first onboarding.

Input	Type	Required	Notes
`workspaceId`	string	Yes	The onboarding workspace ID.

Returns: status, isExpired, chatbotId, claimStatus, checklist (each item with key, label, state, and detail), claimUrl, and onboardingUrl. Side effects: None. Errors: It needs the temporary onboarding token. A connection that signed in to an account gets 403 ONBOARDING_TOKEN_REQUIRED. 404 ONBOARDING_WORKSPACE_NOT_FOUND means the workspace does not exist.

Errors

The chatbot, conversation, appearance, content, and home view tools report an error as text in the form <step> failed: <message> (<CODE>). The code is the API v2 error code. The code tools return API errors inside result. See Code tools.
These errors can come from every tool that reads or changes a chatbot:

Code	Meaning
`401 TOKEN_NOT_VALID`, `401 AUTHORIZATION_HEADER_NOT_VALID`	The credential is not valid. Connect the app again.
`403 PLAN_UPGRADE_REQUIRED`	The account is not on the Growth plan or above.
`403 TOKEN_SCOPE_NOT_ALLOWED`	The connection does not have a needed scope. `details.requiredScopes` lists it.
`404 CHATBOT_NOT_FOUND`	The chatbot does not exist, or the connection or your role cannot access it.
`403 HIPAA_AI_ASSISTANTS_DISABLED`	The chatbot is in a HIPAA workspace, and the tool reads conversations or leads.
`503 HIPAA_CHECK_UNAVAILABLE`	SiteGPT could not check the HIPAA status. Try again in a moment.
`500 INTERNAL_SERVER_ERROR`	An error on the SiteGPT side.

For all API v2 error codes, see API conventions.

Limits

There is no per-request rate limit. 429 means that a plan quota is used up, or with MESSAGE_LIMIT_REACHED, that a conversation reached its message limit. An onboarding start through execute_write can also return 429 RATE_LIMITED, when too many onboarding workspaces were started. Its message says how many minutes to wait. Do not retry it in a loop. See Rate limits and quotas.
A request to the MCP server can be up to 4 MB.
The list tools return up to 100 items for each page. Use nextCursor to get the next page.
The size limits of each input are in the tool sections above. Plan limits are on Plans and limits.

​Connection

​Scopes

​Tool summary

​Code tools

​Chatbot and conversation tools

​preview_chatbot

​send_chat_message

​list_conversations

​get_conversation

​reply_to_conversation

​list_escalations

​list_leads

​get_chatbot_analytics

​Appearance and settings tools

​get_chatbot_appearance

​update_chatbot_appearance

​read_sitegpt_settings

​update_sitegpt_settings

​Content tools

​list_knowledge_sources

​create_knowledge_source

​authorize_knowledge_source

​upload_knowledge_file

​Home view tools

​open_sitegpt and open_sitegpt_inbox

​Onboarding tool

​get_onboarding_status

​Errors

​Limits