customgpt-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a comprehensive CustomGPT MCP Server built with FastMCP 2.0 that provides complete access to CustomGPT.ai APIs through the Model Context Protocol. The server implements 49 tools covering all CustomGPT API endpoints for agent management, conversations, analytics, and content control.

Core Architecture

Main Components

• server.py - Primary MCP server with 49 comprehensive tools using FastMCP framework
• requirements.txt - Dependencies: fastmcp, customgpt-client>=1.2.8, python-dotenv, etc.
• .env - Environment configuration (API keys, server settings)
• docs/ - Complete CustomGPT API documentation including OpenAPI spec

Key Design Patterns

FastMCP Tool Structure:

@mcp.tool()
def tool_name(param: type) -> Dict[str, Any]:
    """Tool description."""
    response = CustomGPT.Class.method(param)
    response_data = extract_response_data(response)  # Critical for serialization
    return {"success": True, "data": response_data}

Response Handling: All CustomGPT SDK methods return Response objects that must be extracted to JSON using extract_response_data(response) before returning to avoid serialization errors.

API Key Management: The server pre-configures CustomGPT client on startup from environment variables, eliminating the need for API key parameters in individual tools.

Development Commands

Environment Setup

# Create Python 3.11+ virtual environment (required for FastMCP)
python3.11 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Configure API key
cp .env.example .env
# Add: CUSTOMGPT_API_KEY=your_key_here

Development Server

# Run MCP server for Claude Code integration
python server.py

# Test server imports and configuration
python -c "from server import mcp; print('✅ Server ready')"

# Run with environment variables
CUSTOMGPT_API_KEY=your_key python server.py