Content
# CustomGPT MCP Server
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.
## Features
### Agent Management
- **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 or files
- **Agent Statistics**: Get usage stats, page counts, and conversation metrics
- **Agent Settings**: View and configure agent behavior and appearance
### Conversation Management
- **Send Messages**: Chat with your agents using OpenAI-compatible format
- **List Conversations**: Browse conversation history for any agent
- **Message History**: Retrieve full conversation transcripts
### Content Management
- **List Pages**: View all pages/sources for your agents
- **Page Status**: Check crawl and indexing status
- **Content Sources**: Manage sitemaps and uploaded files
### API Documentation Integration
- **Search Documentation**: Find relevant API endpoints and documentation
- **Endpoint Details**: Get comprehensive information about specific API endpoints
- **Interactive Help**: Built-in API reference with examples
### Security & Privacy
- **API Key Masking**: Secure API key handling with automatic masking in logs
- **Validation**: Built-in API key validation and format checking
- **No Storage**: Stateless design - API keys are never stored permanently
## Quick Start
### Prerequisites
- **Python 3.10+** (required for FastMCP)
- A valid CustomGPT.ai API key from [CustomGPT Dashboard](https://app.customgpt.ai)
- MCP-compatible client (Claude Code, Claude Web, etc.)
### Installation
#### **Recommended Setup**
```bash
# Clone repository
git clone https://github.com/Poll-The-People/customgpt-mcp.git
cd customgpt-mcp
# Create Python 3.11 virtual environment (required for FastMCP)
python3.11 -m venv venv
source venv/bin/activate
# Install dependencies (includes FastMCP + CustomGPT SDK)
pip install -r requirements.txt
# Configure with your API key
cp .env.example .env
# Edit .env and add: CUSTOMGPT_API_KEY=your_actual_key
# Test the server
python server.py
```
#### Option 2: Using Docker
```bash
git clone https://github.com/customgpt-ai/customgpt-mcp.git
cd customgpt-mcp
docker-compose up -d
```
#### Option 3: Deploy to Railway (Recommended for Production)
[](https://railway.app/template/your-template-id)
1. Click the Railway button above
2. Set your environment variables
3. Deploy with one click
### Local Development
```bash
# Clone the repository
git clone https://github.com/customgpt-ai/customgpt-mcp.git
cd customgpt-mcp
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\\Scripts\\activate
# Install dependencies
pip install -r requirements.txt
# Copy environment file and configure
cp .env.example .env
# Edit .env with your settings
# Run the server
python server.py
```
## 🔧 Configuration
### Environment Variables
Create a `.env` file in the project root:
```env
# API Settings
CUSTOMGPT_API_BASE=https://app.customgpt.ai
API_VERSION=v1
# Server Settings
HOST=0.0.0.0
PORT=8000
DEBUG=false
# CORS Settings
CORS_ORIGINS=https://claude.ai,https://chatgpt.com
# Security
API_KEY_MASK_CHARS=4
```
### MCP Client Configuration
#### Claude Code
Add to your MCP settings:
```json
{
"mcpServers": {
"customgpt": {
"command": "python",
"args": ["/path/to/customgpt-mcp/server.py"],
"env": {
"PYTHONPATH": "/path/to/customgpt-mcp"
}
}
}
}
```
#### Claude Web
1. Go to Claude Web Settings
2. Add MCP Server: `https://your-deployed-server.railway.app`
3. Configure with your CustomGPT API key
## 🛠️ Available Tools
### Agent Management
#### `list_agents`
List all your CustomGPT agents with pagination support.
```json
{
"api_key": "your_customgpt_api_key",
"page": 1,
"name": "filter_by_name",
"order": "desc"
}
```
#### `get_agent`
Get detailed information about a specific agent.
```json
{
"api_key": "your_customgpt_api_key",
"project_id": 123
}
```
#### `create_agent`
Create a new agent from a sitemap or files.
```json
{
"api_key": "your_customgpt_api_key",
"project_name": "My New Agent",
"sitemap_path": "https://example.com/sitemap.xml",
"file_data_retention": true,
"is_ocr_enabled": false,
"is_anonymized": false
}
```
### Conversation Tools
#### `send_message`
Send a message to any of your agents.
```json
{
"api_key": "your_customgpt_api_key",
"project_id": 123,
"message": "Hello, how can you help me?",
"lang": "en",
"stream": false,
"is_inline_citation": false
}
```
#### `list_conversations`
List all conversations for a specific agent.
```json
{
"api_key": "your_customgpt_api_key",
"project_id": 123,
"page": 1,
"order": "desc"
}
```
### Content Management
#### `list_pages`
List all pages/sources for an agent.
```json
{
"api_key": "your_customgpt_api_key",
"project_id": 123,
"page": 1,
"limit": 20,
"crawl_status": "all",
"index_status": "all"
}
```
#### `get_agent_stats`
Get statistics for an agent.
```json
{
"api_key": "your_customgpt_api_key",
"project_id": 123
}
```
#### `get_agent_settings`
Get configuration settings for an agent.
```json
{
"api_key": "your_customgpt_api_key",
"project_id": 123
}
```
### Documentation Tools
#### `search_api_documentation`
Search the CustomGPT API documentation.
```json
{
"query": "create agent",
"category": "Agents"
}
```
#### `get_api_endpoint_details`
Get detailed information about a specific API endpoint.
```json
{
"endpoint_path": "/api/v1/projects",
"method": "POST"
}
```
### Utility Tools
#### `validate_api_key`
Validate your CustomGPT API key.
```json
{
"api_key": "your_customgpt_api_key"
}
```
## 📊 Usage Examples
### Basic Agent Interaction
```python
# 1. Validate your API key
validate_api_key({"api_key": "your_key"})
# 2. List your agents
agents = list_agents({"api_key": "your_key", "page": 1})
# 3. Send a message to an agent
response = send_message({
"api_key": "your_key",
"project_id": 123,
"message": "What can you help me with?"
})
```
### Creating and Managing Agents
```python
# Create a new agent from a sitemap
new_agent = create_agent({
"api_key": "your_key",
"project_name": "Customer Support Bot",
"sitemap_path": "https://mycompany.com/sitemap.xml"
})
# Get agent statistics
stats = get_agent_stats({
"api_key": "your_key",
"project_id": new_agent["agent"]["id"]
})
# List the agent's content pages
pages = list_pages({
"api_key": "your_key",
"project_id": new_agent["agent"]["id"]
})
```
## 🚀 Deployment Options
### Railway (Recommended)
Railway provides the best hosting experience for MCP servers with automatic HTTPS, custom domains, and easy scaling.
1. Fork this repository
2. Connect to Railway
3. Set environment variables
4. Deploy with automatic builds
**Environment Variables for Railway:**
```env
CUSTOMGPT_API_BASE=https://app.customgpt.ai
PORT=8000
PYTHONPATH=.
```
### Vercel
Serverless deployment option for lighter workloads.
1. Install Vercel CLI: `npm i -g vercel`
2. Deploy: `vercel`
3. Set environment variables in Vercel dashboard
### Docker
For containerized deployment on any platform.
```bash
# Build and run
docker-compose up -d
# Or build manually
docker build -t customgpt-mcp .
docker run -p 8000:8000 -e CUSTOMGPT_API_BASE=https://app.customgpt.ai customgpt-mcp
```
### Self-Hosted
For complete control over your deployment.
```bash
# Install dependencies
pip install -r requirements.txt
# Run with Gunicorn (production)
gunicorn -w 4 -k uvicorn.workers.UvicornWorker server:app
# Or run directly (development)
python server.py
```
## 🔍 API Reference
The server provides comprehensive API documentation integration. Use the following tools to explore:
- `search_api_documentation` - Search for specific functionality
- `get_api_endpoint_details` - Get detailed endpoint information
- Access the built-in resource: `customgpt://api-documentation`
## Security Considerations
### API Key Management
- API keys are masked in all logs (only last 4 characters shown)
- Keys are never stored persistently on the server
- Each request validates the API key independently
- Failed authentication attempts are logged for monitoring
### Network Security
- CORS configuration for production environments
- HTTPS enforcement in production
- Request rate limiting (when deployed with proper infrastructure)
- Input validation for all parameters
### Best Practices
1. Use environment variables for configuration
2. Deploy with HTTPS enabled
3. Configure CORS appropriately for your use case
4. Monitor logs for unusual activity
5. Regularly rotate API keys
## Troubleshooting
### Common Issues
#### "Invalid API key format"
- Ensure your API key is correctly formatted
- Check that there are no extra spaces or characters
- Verify the key is from CustomGPT.ai dashboard
#### "Authentication failed"
- API key may be invalid or expired
- Check API key permissions in CustomGPT.ai dashboard
- Try regenerating your API key
#### "Connection timeout"
- Check internet connectivity
- Verify CustomGPT.ai service status
- Ensure firewall isn't blocking requests
#### "API documentation not available"
- Ensure `docs/openapi.json` exists in the project
- Check file permissions
- Verify the JSON file is valid
### Debug Mode
Enable debug logging by setting `DEBUG=true` in your environment:
```bash
DEBUG=true python server.py
```
### Health Checks
The server provides health check endpoints:
- `/health` - Basic server health
- `/api/v1/health` - API health with version info
## Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
### Development Setup
```bash
# Clone and setup
git clone https://github.com/customgpt-ai/customgpt-mcp.git
cd customgpt-mcp
# Install development dependencies
pip install -r requirements.txt
pip install -e ".[dev]"
# Run tests
pytest
# Format code
black .
ruff --fix .
# Type checking
mypy .
```
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Support
- **Documentation**: [https://docs.customgpt.ai/mcp](https://docs.customgpt.ai/)
- **Email**: [hello@customgpt.ai](mailto:hello@customgpt.ai)
- **Slack**: [Join our community](https://customgpt.ai/slack)
## Roadmap
- [ ] **Streaming Support**: Real-time message streaming
- [ ] **File Upload**: Direct file upload to agents
- [ ] **Webhook Integration**: Real-time notifications and events
- [ ] **Multi-tenancy**: Support for multiple organizations
- [ ] **Rate Limiting**: Built-in rate limiting and quota management
- [ ] **Caching**: Intelligent response caching for better performance
*this is still in beta.
