A full-featured Model Context Protocol (MCP) server that provides seamless access to CustomGPT.ai APIs. Interact with your CustomGPT agents directly through Claude Code, Claude Web, and any MCP-compatible client. - List Agents: Browse all your CustomGPT agents with pagination - Get Agent Details: Retrieve detailed information about specific agents - Create Agents: Create new agents from sitemaps o
Add this skill
npx mdskills install Poll-The-People/customgpt-mcpComprehensive MCP server connecting Claude to CustomGPT.ai APIs with extensive agent and conversation tools
1# CustomGPT MCP Server23A **full-featured** Model Context Protocol (MCP) server that provides seamless access to CustomGPT.ai APIs. Interact with your CustomGPT agents directly through Claude Code, Claude Web, and any MCP-compatible client.45## Features67### Agent Management8- **List Agents**: Browse all your CustomGPT agents with pagination9- **Get Agent Details**: Retrieve detailed information about specific agents10- **Create Agents**: Create new agents from sitemaps or files11- **Agent Statistics**: Get usage stats, page counts, and conversation metrics12- **Agent Settings**: View and configure agent behavior and appearance1314### Conversation Management15- **Send Messages**: Chat with your agents using OpenAI-compatible format16- **List Conversations**: Browse conversation history for any agent17- **Message History**: Retrieve full conversation transcripts1819### Content Management20- **List Pages**: View all pages/sources for your agents21- **Page Status**: Check crawl and indexing status22- **Content Sources**: Manage sitemaps and uploaded files2324### API Documentation Integration25- **Search Documentation**: Find relevant API endpoints and documentation26- **Endpoint Details**: Get comprehensive information about specific API endpoints27- **Interactive Help**: Built-in API reference with examples2829### Security & Privacy30- **API Key Masking**: Secure API key handling with automatic masking in logs31- **Validation**: Built-in API key validation and format checking32- **No Storage**: Stateless design - API keys are never stored permanently3334## Quick Start3536### Prerequisites37- **Python 3.10+** (required for FastMCP)38- A valid CustomGPT.ai API key from [CustomGPT Dashboard](https://app.customgpt.ai)39- MCP-compatible client (Claude Code, Claude Web, etc.)4041### Installation4243#### **Recommended Setup**44```bash45# Clone repository46git clone https://github.com/Poll-The-People/customgpt-mcp.git47cd customgpt-mcp4849# Create Python 3.11 virtual environment (required for FastMCP)50python3.11 -m venv venv51source venv/bin/activate5253# Install dependencies (includes FastMCP + CustomGPT SDK)54pip install -r requirements.txt5556# Configure with your API key57cp .env.example .env58# Edit .env and add: CUSTOMGPT_API_KEY=your_actual_key5960# Test the server61python server.py62```6364#### Option 2: Using Docker65```bash66git clone https://github.com/customgpt-ai/customgpt-mcp.git67cd customgpt-mcp68docker-compose up -d69```7071#### Option 3: Deploy to Railway (Recommended for Production)72[](https://railway.app/template/your-template-id)73741. Click the Railway button above752. Set your environment variables763. Deploy with one click7778### Local Development79```bash80# Clone the repository81git clone https://github.com/customgpt-ai/customgpt-mcp.git82cd customgpt-mcp8384# Create virtual environment85python -m venv venv86source venv/bin/activate # On Windows: venv\\Scripts\\activate8788# Install dependencies89pip install -r requirements.txt9091# Copy environment file and configure92cp .env.example .env93# Edit .env with your settings9495# Run the server96python server.py97```9899## 🔧 Configuration100101### Environment Variables102103Create a `.env` file in the project root:104105```env106# API Settings107CUSTOMGPT_API_BASE=https://app.customgpt.ai108API_VERSION=v1109110# Server Settings111HOST=0.0.0.0112PORT=8000113DEBUG=false114115# CORS Settings116CORS_ORIGINS=https://claude.ai,https://chatgpt.com117118# Security119API_KEY_MASK_CHARS=4120```121122### MCP Client Configuration123124#### Claude Code125Add to your MCP settings:126```json127{128 "mcpServers": {129 "customgpt": {130 "command": "python",131 "args": ["/path/to/customgpt-mcp/server.py"],132 "env": {133 "PYTHONPATH": "/path/to/customgpt-mcp"134 }135 }136 }137}138```139140#### Claude Web1411. Go to Claude Web Settings1422. Add MCP Server: `https://your-deployed-server.railway.app`1433. Configure with your CustomGPT API key144145## 🛠️ Available Tools146147### Agent Management148149#### `list_agents`150List all your CustomGPT agents with pagination support.151```json152{153 "api_key": "your_customgpt_api_key",154 "page": 1,155 "name": "filter_by_name",156 "order": "desc"157}158```159160#### `get_agent`161Get detailed information about a specific agent.162```json163{164 "api_key": "your_customgpt_api_key",165 "project_id": 123166}167```168169#### `create_agent`170Create a new agent from a sitemap or files.171```json172{173 "api_key": "your_customgpt_api_key",174 "project_name": "My New Agent",175 "sitemap_path": "https://example.com/sitemap.xml",176 "file_data_retention": true,177 "is_ocr_enabled": false,178 "is_anonymized": false179}180```181182### Conversation Tools183184#### `send_message`185Send a message to any of your agents.186```json187{188 "api_key": "your_customgpt_api_key",189 "project_id": 123,190 "message": "Hello, how can you help me?",191 "lang": "en",192 "stream": false,193 "is_inline_citation": false194}195```196197#### `list_conversations`198List all conversations for a specific agent.199```json200{201 "api_key": "your_customgpt_api_key",202 "project_id": 123,203 "page": 1,204 "order": "desc"205}206```207208### Content Management209210#### `list_pages`211List all pages/sources for an agent.212```json213{214 "api_key": "your_customgpt_api_key",215 "project_id": 123,216 "page": 1,217 "limit": 20,218 "crawl_status": "all",219 "index_status": "all"220}221```222223#### `get_agent_stats`224Get statistics for an agent.225```json226{227 "api_key": "your_customgpt_api_key",228 "project_id": 123229}230```231232#### `get_agent_settings`233Get configuration settings for an agent.234```json235{236 "api_key": "your_customgpt_api_key",237 "project_id": 123238}239```240241### Documentation Tools242243#### `search_api_documentation`244Search the CustomGPT API documentation.245```json246{247 "query": "create agent",248 "category": "Agents"249}250```251252#### `get_api_endpoint_details`253Get detailed information about a specific API endpoint.254```json255{256 "endpoint_path": "/api/v1/projects",257 "method": "POST"258}259```260261### Utility Tools262263#### `validate_api_key`264Validate your CustomGPT API key.265```json266{267 "api_key": "your_customgpt_api_key"268}269```270271## 📊 Usage Examples272273### Basic Agent Interaction274```python275# 1. Validate your API key276validate_api_key({"api_key": "your_key"})277278# 2. List your agents279agents = list_agents({"api_key": "your_key", "page": 1})280281# 3. Send a message to an agent282response = send_message({283 "api_key": "your_key",284 "project_id": 123,285 "message": "What can you help me with?"286})287```288289### Creating and Managing Agents290```python291# Create a new agent from a sitemap292new_agent = create_agent({293 "api_key": "your_key",294 "project_name": "Customer Support Bot",295 "sitemap_path": "https://mycompany.com/sitemap.xml"296})297298# Get agent statistics299stats = get_agent_stats({300 "api_key": "your_key",301 "project_id": new_agent["agent"]["id"]302})303304# List the agent's content pages305pages = list_pages({306 "api_key": "your_key",307 "project_id": new_agent["agent"]["id"]308})309```310311## 🚀 Deployment Options312313### Railway (Recommended)314Railway provides the best hosting experience for MCP servers with automatic HTTPS, custom domains, and easy scaling.3153161. Fork this repository3172. Connect to Railway3183. Set environment variables3194. Deploy with automatic builds320321**Environment Variables for Railway:**322```env323CUSTOMGPT_API_BASE=https://app.customgpt.ai324PORT=8000325PYTHONPATH=.326```327328### Vercel329Serverless deployment option for lighter workloads.3303311. Install Vercel CLI: `npm i -g vercel`3322. Deploy: `vercel`3333. Set environment variables in Vercel dashboard334335### Docker336For containerized deployment on any platform.337338```bash339# Build and run340docker-compose up -d341342# Or build manually343docker build -t customgpt-mcp .344docker run -p 8000:8000 -e CUSTOMGPT_API_BASE=https://app.customgpt.ai customgpt-mcp345```346347### Self-Hosted348For complete control over your deployment.349350```bash351# Install dependencies352pip install -r requirements.txt353354# Run with Gunicorn (production)355gunicorn -w 4 -k uvicorn.workers.UvicornWorker server:app356357# Or run directly (development)358python server.py359```360361## 🔍 API Reference362363The server provides comprehensive API documentation integration. Use the following tools to explore:364365- `search_api_documentation` - Search for specific functionality366- `get_api_endpoint_details` - Get detailed endpoint information367- Access the built-in resource: `customgpt://api-documentation`368369## Security Considerations370371### API Key Management372- API keys are masked in all logs (only last 4 characters shown)373- Keys are never stored persistently on the server374- Each request validates the API key independently375- Failed authentication attempts are logged for monitoring376377### Network Security378- CORS configuration for production environments379- HTTPS enforcement in production380- Request rate limiting (when deployed with proper infrastructure)381- Input validation for all parameters382383### Best Practices3841. Use environment variables for configuration3852. Deploy with HTTPS enabled3863. Configure CORS appropriately for your use case3874. Monitor logs for unusual activity3885. Regularly rotate API keys389390## Troubleshooting391392### Common Issues393394#### "Invalid API key format"395- Ensure your API key is correctly formatted396- Check that there are no extra spaces or characters397- Verify the key is from CustomGPT.ai dashboard398399#### "Authentication failed"400- API key may be invalid or expired401- Check API key permissions in CustomGPT.ai dashboard402- Try regenerating your API key403404#### "Connection timeout"405- Check internet connectivity406- Verify CustomGPT.ai service status407- Ensure firewall isn't blocking requests408409#### "API documentation not available"410- Ensure `docs/openapi.json` exists in the project411- Check file permissions412- Verify the JSON file is valid413414### Debug Mode415Enable debug logging by setting `DEBUG=true` in your environment:416417```bash418DEBUG=true python server.py419```420421### Health Checks422The server provides health check endpoints:423- `/health` - Basic server health424- `/api/v1/health` - API health with version info425426## Contributing427428We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.429430### Development Setup431```bash432# Clone and setup433git clone https://github.com/customgpt-ai/customgpt-mcp.git434cd customgpt-mcp435436# Install development dependencies437pip install -r requirements.txt438pip install -e ".[dev]"439440# Run tests441pytest442443# Format code444black .445ruff --fix .446447# Type checking448mypy .449```450451## License452453This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.454455## Support456457- **Documentation**: [https://docs.customgpt.ai/mcp](https://docs.customgpt.ai/)458- **Email**: [hello@customgpt.ai](mailto:hello@customgpt.ai)459- **Slack**: [Join our community](https://customgpt.ai/slack)460461## Roadmap462463- [ ] **Streaming Support**: Real-time message streaming464- [ ] **File Upload**: Direct file upload to agents465- [ ] **Webhook Integration**: Real-time notifications and events466- [ ] **Multi-tenancy**: Support for multiple organizations467- [ ] **Rate Limiting**: Built-in rate limiting and quota management468- [ ] **Caching**: Intelligent response caching for better performance469470471*this is still in beta.
Full transparency — inspect the skill content before installing.