> ## Documentation Index > Fetch the complete documentation index at: https://sitegpt.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # MCP tool reference > Each tool of the remote SiteGPT MCP server: access type, scopes, personal data, side effects, inputs, outputs, errors, and limits. 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](/docs/developers/mcp). The local server (`sitegpt mcp`) has other tools. See [Local server tools](/docs/developers/mcp#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](/docs/developers/authentication). | | Plan | Growth plan and above. See [Plans and limits](/docs/reference/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](/docs/developers/authentication#scopes). 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](/docs/developers/mcp#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](/docs/developers/mcp#hipaa-workspaces), 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](/docs/api-reference/v2/conventions#deletes-need-confirmation). | * The scopes, inputs, outputs, and errors of each operation are in the [API reference](/docs/api-reference/v2/getting-started). * 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](/docs/guides/content/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](/docs/reference/glossary), `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](/docs/reference/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](/docs/guides/human-support/reply-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 `__`, where `` 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](/docs/cli/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 ` failed: ()`. The code is the API v2 error code. The code tools return API errors inside `result`. See [Code tools](#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](/docs/api-reference/v2/conventions#errors). ## 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](/docs/api-reference/v2/conventions#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](/docs/reference/plans-and-limits). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.