CustomGPT MCP Server is an open-source full-featured Model Context Protocol (MCP) server designed to provide seamless access to the CustomGPT.ai API. Through this server, users can interact directly with their CustomGPT agents in Claude Code, Claude Web, and any MCP-compatible client.
Purpose
The server serves as the MCP interface for CustomGPT.ai, allowing users to manage agents, conduct conversations, manage content, and consult API documentation through MCP-compatible clients (such as Claude Code, Claude Web).
Key Capabilities
- Agent Management: List all agents (with pagination support), get detailed information for a specific agent, create new agents from a sitemap or files, get usage statistics (page count, conversation metrics), view and configure agent behavior and appearance.
- Conversation Management: Send messages to agents using an OpenAI-compatible format, list the conversation history of any agent, retrieve complete conversation records.
- Content Management: List all pages/sources of an agent, check crawl and index status, manage sitemaps and uploaded files.
- API Documentation Integration: Search relevant API endpoints and documentation, get detailed information for a specific API endpoint, built-in API reference with examples.
- Security and Privacy: API key masking (only the last 4 digits are shown in logs), built-in API key validation and format checking, stateless design (keys are never permanently stored).
Usage
Environment Requirements
- Python 3.10+ (required by FastMCP)
- A valid CustomGPT.ai API key (obtained from the CustomGPT Dashboard)
- An MCP-compatible client (Claude Code, Claude Web, etc.)
Deployment Options
- Railway (recommended): Provides automatic HTTPS, custom domains, and easy scaling. Click the Railway button, set environment variables, and deploy with one click.
- Vercel: Suitable for serverless deployment with lighter loads. Install the Vercel CLI (
npm i -g vercel), set environment variables in the Vercel dashboard. - Docker: Containerized deployment suitable for any platform.
- Local Development: Create a
.envfile in the project root directory and configure environment variables.
MCP Client Configuration
- Add the server address in the MCP settings (such as
https://your-deployed-server.railway.app), and configure the CustomGPT API key. - For Claude Web: Go to settings, add the MCP server, and configure the API key.
Available Tools
- Agent Tools: List agents, get agent details, create agents.
- Conversation Tools: Send messages, list conversations.
- Content Tools: List pages/sources, get statistics, get settings.
- Documentation Tools: Search API documentation, get endpoint details, validate API keys.
Security Considerations
- API keys are masked in all logs (only the last 4 digits are shown), never permanently stored, and independently validated on each request.
- For production environments, it is recommended to enable HTTPS, configure CORS, monitor logs, and regularly rotate API keys.
Troubleshooting
- Ensure the API key format is correct, with no extra spaces or characters, and comes from the CustomGPT.ai dashboard.
- Check API key permissions and try regenerating it.
- Check the network connection, CustomGPT.ai service status, and firewall settings.
- Ensure that
docs/openapi.jsonexists and is valid. - Debug logging can be enabled by setting
DEBUG=true. - Health check endpoints:
/health(basic health),/api/v1/health(API health with version information).
Use Cases
Suitable for developers and users who need to manage CustomGPT.ai agents, conduct conversational interactions, manage content, and consult API documentation through MCP clients (such as Claude Code, Claude Web).
Limitations
- The project is still in beta.
- Requires a Python 3.10+ environment.
- Requires a valid CustomGPT.ai API key.
- Requires an MCP-compatible client.
Other Information
- License: MIT
- Documentation:https://docs.customgpt.ai/mcp
- Contact: hello@customgpt.ai
- Future plans: streaming support, file upload, Webhook integration, multi-tenancy, rate limiting, caching.
