CorpusIQ

Quick Start Guide

Quick Start Guide

Get CorpusIQ Apps SDK running in under 5 minutes for local testing with ChatGPT.

Prerequisites

  • Python 3.10 or higher
  • Git
  • Terminal/Command prompt

Step 1: Clone and Install (2 minutes)

# Clone repository
git clone https://github.com/CorpusIQ/corpusiq-openai-sdk.git
cd corpusiq-openai-sdk

# Create virtual environment
python3 -m venv .venv

# Activate virtual environment
# On macOS/Linux:
source .venv/bin/activate
# On Windows:
# .venv\Scripts\activate

# Install dependencies
pip install -e .

Step 2: Configure (1 minute)

# Copy environment file
cp .env.example .env

# Edit configuration (optional for testing)
# nano .env  # or use your favorite editor

For local testing, you can leave defaults. The key settings are:

# Allow ChatGPT to connect (required)
CORPUSIQ_CORS_ALLOW_ORIGINS_CSV=https://chat.openai.com

# Disable debug mode in production only
CORPUSIQ_DEBUG_MODE=false

Step 3: Start Server (30 seconds)

# Start the server
python -m corpusiq

You should see:

INFO: Starting CorpusIQ Apps SDK server...
INFO: Uvicorn running on http://0.0.0.0:8000

Keep this terminal open!

Step 4: Create HTTPS Tunnel (1 minute)

ChatGPT requires HTTPS. Choose one option:

# Install cloudflared (one-time)
# macOS:
brew install cloudflare/cloudflare/cloudflared
# Windows: Download from https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/
# Linux:
wget https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
sudo dpkg -i cloudflared-linux-amd64.deb

# In a NEW terminal, create tunnel
cloudflared tunnel --url http://localhost:8000

You’ll see output like:

Your quick Tunnel has been created! Visit it at:
https://abc123def456.trycloudflare.com

Copy this URL! You’ll need it for ChatGPT.

Option B: ngrok

# Install ngrok (one-time)
# See: https://ngrok.com/download

# In a NEW terminal, create tunnel
ngrok http 8000

Copy the HTTPS forwarding URL (e.g., https://xyz123.ngrok.io)

Step 5: Connect to ChatGPT (1 minute)

  1. Open ChatGPT at https://chat.openai.com

  2. Enable Developer Mode:

    • Click your profile → Settings
    • Go to Apps & Connectors → Advanced Settings
    • Toggle Developer Mode ON

  3. Add Connector:

    • In Settings, go to Apps & Connectors
    • Click Create Connector (or similar button)
    • Paste your tunnel URL (from Step 4)
    • Click Connect or Save

ChatGPT will discover your MCP server automatically!

Step 6: Test It! (30 seconds)

In ChatGPT, try these prompts:

Search my corpus for "project updates"

Show me my connected data sources

Open the connectors interface

You should see:

  • An interactive widget with search functionality
  • A list of available connectors (Gmail, OneDrive, etc.)
  • Results displayed beautifully in the interface

Troubleshooting

Server won’t start

Error: ModuleNotFoundError: No module named 'corpusiq'

Solution: Make sure you’re in the virtual environment and installed the package:

source .venv/bin/activate  # or .venv\Scripts\activate on Windows
pip install -e .

ChatGPT can’t connect

Error: Connection timeout or “Can’t reach server”

Solutions:

  1. Verify tunnel is running (check the terminal)
  2. Verify server is running (check the other terminal)
  3. Copy the HTTPS URL exactly (include https://)
  4. Check CORS is configured to allow https://chat.openai.com

Widget not showing

Error: Tools work but widget doesn’t display

Solution: Check that assets/corpusiq.html exists:

ls -la assets/

If missing, the widget file may not have been cloned. Try:

git pull origin main

Rate limited

Error: 429 Too Many Requests

Solution: Wait 60 seconds, or increase rate limit in .env:

CORPUSIQ_RATE_LIMIT_REQUESTS_PER_MINUTE=120

Then restart the server.

Next Steps

Now that it’s working:

  1. Customize the tools - Edit src/corpusiq/mcp_server.py to add your own functionality
  2. Add OAuth - Follow DEPLOYMENT.md to add authentication
  3. Deploy to production - See DEPLOYMENT.md for deployment options
  4. Submit to OpenAI - Review SUBMISSION_CHECKLIST.md when ready

Stopping the Server

# In the server terminal, press Ctrl+C
# Then deactivate virtual environment:
deactivate

Development Workflow

When making changes:

# 1. Make your changes to the code

# 2. Restart the server (Ctrl+C, then run again)
python -m corpusiq

# 3. Refresh connector in ChatGPT
#    Settings → Apps & Connectors → Your Connector → Refresh

# 4. Test your changes

Common Development Tasks

Run linter

pip install ruff
ruff check src/
ruff format src/

View logs

Server logs appear in the terminal. For more detail:

# Set debug logging in .env
CORPUSIQ_LOG_LEVEL=DEBUG

# Restart server
python -m corpusiq

Test endpoints manually

# Health check
curl http://localhost:8000/

# OAuth metadata
curl http://localhost:8000/.well-known/oauth-protected-resource

# Debug tools (if DEBUG_MODE=true)
curl http://localhost:8000/debug/tools

Resources

Getting Help

  • Issues: Create an issue in the GitHub repository
  • Documentation: Check the README and other .md files
  • OpenAI Support: https://help.openai.com/

What You’ve Accomplished

✅ Installed CorpusIQ Apps SDK
✅ Started the MCP server
✅ Connected it to ChatGPT
✅ Tested the tools and widget
✅ Ready to build and customize!

Happy building! 🚀