# Customgpt — how to use (mcp.ai)

Connect your Customgpt account and use 40 tools for AI chatbots straight from your AI agent. Connect with your own API key. CustomGPT.ai is a platform that enables users to create and integrate AI-powered chatbots tailored to their specific data and requirements.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_customgpt?ms=1787293500000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `customgpt_activate_persona_version`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/customgpt`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/customgpt/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/customgpt/activate/persona/version` — Restore a previous persona version for a CustomGPT agent. Activates a previous persona version, making it the current active persona. This creates a new version entry in the history (it doesn't overwr
  - body: { version: integer, projectId: integer }
- `POST https://api.mcp.ai/api/customgpt/add/source` — Add a data source to a CustomGPT agent's knowledge base. Connects content via sitemap URL, file upload, or integration. The system begins indexing immediately after creation. Use when adding documenta
  - body: { file?: object, project_id: integer, sitemap_path?: string, is_anonymized?: boolean, is_ocr_enabled?: boolean, is_vision_enabled?: boolean, file_data_retension?: boolean, image_extraction_type?: string, is_vision_compress_image?: boolean }
- `POST https://api.mcp.ai/api/customgpt/clone/project` — Tool to clone a CustomGPT agent (project). Creates a complete copy of an existing agent, including its knowledge base, persona, and settings. Use this to create variations of an agent for testing, or 
  - body: { projectId: integer }
- `POST https://api.mcp.ai/api/customgpt/create/conversation` — Tool to create a new conversation session for a CustomGPT agent. Use this when starting a new chat interaction - it returns a session ID that you'll use to send messages. Optionally provide a name to 
  - body: { name?: string, projectId: integer }
- `POST https://api.mcp.ai/api/customgpt/create/project` — Tool to create a new CustomGPT agent from a sitemap URL or file upload. The agent immediately begins processing the content to build its knowledge base. Use when you need to create a new AI agent with
  - body: { file?: object, project_name: string, sitemap_path?: string, is_anonymized?: boolean, is_ocr_enabled?: boolean, is_vision_enabled?: boolean, file_data_retension?: boolean, is_vision_compress_image?: boolean }
- `POST https://api.mcp.ai/api/customgpt/delete/page` — Tool to delete a document from a CustomGPT agent's knowledge base. Permanently removes a document and the agent will no longer reference this content when answering questions. Use this to remove outda
  - body: { pageId: integer, projectId: integer }
- `POST https://api.mcp.ai/api/customgpt/delete/project` — Tool to delete a CustomGPT project by ID. Use when you need to permanently remove an existing agent after confirming the ID.
  - body: { projectId: string }
- `POST https://api.mcp.ai/api/customgpt/delete/project/license` — Deletes a license from a CustomGPT project/agent. Requires numeric project ID and license ID. This action is idempotent - it succeeds even if the license doesn't exist (404). The project must have lic
  - body: { licenseId: string, projectId: string }
- `POST https://api.mcp.ai/api/customgpt/delete/source` — Tool to delete a data source from a CustomGPT agent. Removes the source and all its documents from the agent's knowledge base. Use this to disconnect content that's no longer relevant or to clean up a
  - body: { sourceId: integer, projectId: integer }
- `POST https://api.mcp.ai/api/customgpt/export/leads` — Export leads from a CustomGPT project. Returns lead information captured from conversations including email addresses, names, phone numbers, and custom fields. Supports pagination and date range filte
  - body: { page?: integer, limit?: integer, end_date?: string, projectId: integer, start_date?: string }
- `POST https://api.mcp.ai/api/customgpt/get/message` — Tool to get message details from a CustomGPT conversation. Returns the complete details for a single message, including the user's prompt, the agent's response, timestamps, citations, and any attached
  - body: { promptId: integer, projectId: integer, sessionId: string, includeInsights?: string[] }
- `POST https://api.mcp.ai/api/customgpt/get/message/trust/score` — Tool to retrieve verification trust score for a message in a CustomGPT conversation. Returns a score calculated by checking how well the agent's claims are supported by source documents. Higher scores
  - body: { promptId: integer, projectId: integer, sessionId: string }
- `POST https://api.mcp.ai/api/customgpt/get/page/metadata` — Tool to get document metadata including title, source URL, word count, and custom metadata fields. Use this to display document information or manage your knowledge base.
  - body: { pageId: string, projectId: integer }
- `POST https://api.mcp.ai/api/customgpt/get/plugins` — Tool to retrieve plugin details for a specific CustomGPT agent (project). Use when you need to inspect plugin configuration, status, and metadata for an agent.
  - body: { projectId: integer }
- `POST https://api.mcp.ai/api/customgpt/get/project` — Tool to get agent details. Returns the full configuration and current status for a specific agent. Use this to check processing status, view settings, or retrieve metadata about the agent.
  - body: { width?: string, height?: string, projectId: integer }
- `POST https://api.mcp.ai/api/customgpt/get/project/license` — Tool to retrieve a license for a specific project. Use when you need to fetch license details by license ID.
  - body: { licenseId: string, projectId: string }
- `POST https://api.mcp.ai/api/customgpt/get/project/settings` — Retrieve configuration settings for a specific CustomGPT agent/project. Returns settings including: chatbot avatar, background, default prompt, example questions, response source, language, and brandi
  - body: { projectId: string }
- `POST https://api.mcp.ai/api/customgpt/get/report/analysis` — Tool to retrieve analytics chart data for a CustomGPT project. Returns time-series data formatted for charts, with daily or weekly breakdowns of key metrics including conversation counts, query counts
  - body: { filters: string[], interval?: string, project_id: integer }
- `POST https://api.mcp.ai/api/customgpt/get/report/conversations` — Tool to get conversation analytics for a CustomGPT project. Returns conversation metrics including total conversations, average queries per conversation, and other engagement statistics. Use this to u
  - body: { filters?: string, project_id: integer }
- `POST https://api.mcp.ai/api/customgpt/get/report/intelligence` — Tool to get customer intelligence for a CustomGPT project. Returns AI-analyzed insights about users including common intents, emotional sentiment, frequently discussed topics, and emerging trends. Use
  - body: { page?: integer, leads?: integer[], limit?: integer, country?: string[], user_id?: integer[], accuracy?: string, end_date?: string, language?: string[], project_id: integer, start_date?: string, external_id?: string[], user_intent?: string[], user_emotion?: string[], risk_fidelity?: string[], content_source?: string[], request_source?: string[], risk_jailbreak?: string[], risk_profanity?: string[], stakeholder_status?: string[], risk_prompt_leakage?: string[] }
- `POST https://api.mcp.ai/api/customgpt/get/report/traffic` — Tool to retrieve traffic analytics for a CustomGPT agent/project. Returns user traffic metrics including unique visitors, session counts, geographic distribution, and device types. Use this to underst
  - body: { filters?: object[], project_id: integer }
- `POST https://api.mcp.ai/api/customgpt/get/stats` — Tool to get agent statistics. Returns usage metrics and performance statistics for an agent, including total conversations, query counts, document statistics, and processing information. Use when you 
  - body: { project_id: integer }
- `POST https://api.mcp.ai/api/customgpt/get/usage/limits` — Get account usage limits showing current usage vs. maximum allowed for projects, storage credits, and API queries. This returns how many projects, storage credits (characters indexed), and queries you
- `POST https://api.mcp.ai/api/customgpt/get/user/profile` — Tool to retrieve the current user's profile information. Use when you need to display or verify authenticated user details after login.
- `POST https://api.mcp.ai/api/customgpt/list/conversation/messages` — Retrieves all messages from a CustomGPT conversation, including both user queries and AI responses. Use this to view the complete chat history for a specific conversation session. Returns an empty lis
  - body: { projectId: string, sessionId: string }
- `POST https://api.mcp.ai/api/customgpt/list/pages` — Lists all documents in a CustomGPT agent's knowledge base. Returns indexed content including webpages, PDFs, and uploaded files that the agent can reference. Supports filtering by crawl/index status a
  - body: { page?: integer, limit?: integer, order?: string, projectId: integer, crawlStatus?: string, indexStatus?: string }
- `POST https://api.mcp.ai/api/customgpt/list/personas` — Tool to list persona versions for a CustomGPT agent. Use when you need to view the version history of an agent's persona. Every time the persona is updated, a snapshot is automatically saved, allowing
  - body: { page?: integer, limit?: integer, project_id: integer }
- `POST https://api.mcp.ai/api/customgpt/list/project/licenses` — List all licenses for a CustomGPT project/agent. Returns an array of license objects with details like ID, type, status, and timestamps. Returns an empty array if the project has no licenses or if lic
  - body: { projectId: string }
- `POST https://api.mcp.ai/api/customgpt/list/projects` — Lists all CustomGPT projects (agents) for the authenticated user. Returns projects with full details including ID, name, type, chat status, and timestamps. Supports pagination via the 'page' parameter
  - body: { page?: integer }
- `POST https://api.mcp.ai/api/customgpt/list/sources` — Tool to list all data sources connected to an agent. Returns sources from various origins like sitemaps, Google Drive folders, SharePoint sites, or uploaded files. Use this to manage what content feed
  - body: { project_id: integer }
- `POST https://api.mcp.ai/api/customgpt/reindex/page` — Tool to reindex a document in CustomGPT knowledge base. Re-crawls and re-indexes a URL-based document to update its content. Use this when the source content has changed and you want the agent to use 
  - body: { pageId: integer, projectId: integer }
- `POST https://api.mcp.ai/api/customgpt/search/team/members` — Tool to search for team members by email address or user ID. Use this to find users when assigning permissions or managing team access. Requires Owner or Admin role to execute.
  - body: { email?: string, user_id?: integer }
- `POST https://api.mcp.ai/api/customgpt/submit/message/feedback` — Tool to submit feedback (thumbs up/down) for a message in a CustomGPT conversation. Use this to record user satisfaction signals that help identify which AI responses are helpful and which need improv
  - body: { promptId: integer, reaction: string, projectId: integer, sessionId: string, includeInsights?: string[] }
- `POST https://api.mcp.ai/api/customgpt/update/page/metadata` — Update document metadata for a specific page in a CustomGPT project. Updates custom metadata fields such as title, description, URL, and image that help organize and manage your knowledge base. Use wh
  - body: { url?: string, image?: string, title?: string, pageId: integer, projectId: integer, description?: string }
- `POST https://api.mcp.ai/api/customgpt/update/project` — Updates an existing CustomGPT agent's name or configuration settings. Use this to rename an agent or modify its basic properties without affecting its knowledge base. Returns the complete updated proj
  - body: { is_shared?: boolean, project_id: integer, project_name?: string, sitemap_path?: string, is_anonymized?: boolean, is_ocr_enabled?: boolean, file_data_retension?: boolean, are_licenses_allowed?: boolean }
- `POST https://api.mcp.ai/api/customgpt/update/project/license` — Updates the name of an existing license for a CustomGPT project/agent. Prerequisites: - The project must have licenses enabled in its plan - Both project ID and license ID must be valid and exist - Us
  - body: { name: string, licenseId: string, projectId: string }
- `POST https://api.mcp.ai/api/customgpt/update/project/settings` — Update CustomGPT agent configuration settings. Updates persona instructions, response format, citation style, branding, and deployment settings. Only include fields you want to change - omitted fields
  - body: { projectId: integer, chat_bot_bg?: object, font_family?: string, user_avatar?: object, chatbot_color?: string, chatbot_model?: string, chatbot_title?: string, view_less_msg?: string, view_more_msg?: string, default_prompt?: string, ending_message?: string, radius_styling?: string, user_awareness?: boolean, chat_bot_avatar?: object, remove_branding?: boolean, response_source?: string, agent_capability?: string, chat_bot_bg_type?: string, chatbot_msg_lang?: string, enable_citations?: integer, enable_feedbacks?: boolean, is_hybrid_search?: boolean, markdown_enabled?: boolean, spotlight_avatar?: object, chat_bot_bg_color?: string, example_questions?: string[], hang_in_there_msg?: string, no_answer_message?: string, chatbot_siesta_msg?: string, is_selling_enabled?: boolean, chatbot_title_color?: string, citations_view_type?: string, user_avatar_enabled?: boolean, input_field_addendum?: string, persona_instructions?: string, title_avatar_enabled?: boolean, chat_bot_color_scheme?: string, chatbot_toolbar_color?: string, spotlight_avatar_type?: string, can_share_conversation?: boolean, image_citation_display?: string, spotlight_avatar_shape?: string, can_export_conversation?: boolean, user_avatar_orientation?: string, conversation_time_window?: integer, spotlight_avatar_enabled?: boolean, try_asking_questions_msg?: string, citations_sources_label_msg?: string, conversation_retention_days?: integer, enable_inline_citations_api?: boolean, hide_sources_from_responses?: boolean, limit_image_citation_height?: boolean, agent_title_avatar_alignment?: string, is_loading_indicator_enabled?: boolean, use_opengraph_image_citation?: boolean, chatbot_failed_moderation_msg?: string, conversation_retention_period?: string, citations_answer_source_label_msg?: string, use_context_aware_starter_question?: boolean, enable_recaptcha_for_public_chatbots?: boolean, enable_agent_knowledge_base_awareness?: boolean }
- `POST https://api.mcp.ai/api/customgpt/update/source` — Update source settings for a CustomGPT agent data source. Configure how the source is indexed and kept up to date by adjusting auto-sync frequency, crawl depth, file filters, and refresh behavior. Use
  - body: { source_id: integer, project_id: integer, executive_js?: boolean, create_new_pages?: boolean, refresh_schedule?: object, allow_extra_timeout?: boolean, remove_unexist_pages?: boolean, image_extraction_type?: string, data_refresh_frequency?: string, refresh_existing_pages?: string, update_existing_images?: boolean }
- `POST https://api.mcp.ai/api/customgpt/update/user/profile` — Updates the authenticated user's profile information in CustomGPT. Use this action to modify profile details such as the user's display name, email address, or profile photo URL. All fields are option
  - body: { name?: string, email?: string, profile_photo_url?: string }
- `POST https://api.mcp.ai/api/customgpt/verify/message` — Tool to verify message accuracy by triggering a fact-checking verification process. Use when you need to verify claims in a conversation message against source documents. The system compares each clai
  - body: { promptId: integer, projectId: integer, sessionId: string }

## Example prompts
- "What can I do in Customgpt?"
- "Show me a summary of my Customgpt account"

## More
- Page: https://mcp.ai/customgpt
- Agent spec (llms.txt): https://mcp.ai/customgpt/llms.txt
- Postman collection: https://mcp.ai/customgpt/postman.json