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, and reply to visitors.

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. 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. 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), 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). 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. 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, or on WhatsApp for a WhatsApp conversation.
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.
Each call sends another message.

Status: If a WhatsApp message cannot be delivered, delivery.delivered is false and delivery.reason tells why. Errors: 409 CONVERSATION_CLOSED (the conversation is resolved), 409 REPLY_IN_CHANNEL (the conversation is on Slack, Crisp, Messenger, 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 for up to 10 chatbots: lead email notifications, human handoff, how new conversations start, and hide sources in answers. It takes no input. Returns: schema, values, and layout. Each setting is named <field>__<chatbotId>, where <field> is leadEmails, humanSupport, chatMode (AI or AGENT), or hideSources. 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` or `AGENT`. 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. Errors: An unknown setting name or a value that is not valid fails before anything is saved. 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. The view’s reply form sends the reply as a reply_to_conversation call through the app. The view sends nothing to the visitor by itself.

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, and SiteGPT sends no rate-limit headers. 429 means that a plan quota is used up. 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