basicmachines-co-basic-memory/v15-docs/chatgpt-integration.md

ChatGPT MCP Integration

Status: New Feature PR: #305 File: mcp/tools/chatgpt_tools.py Mode: Remote MCP only

What's New

v0.15.0 introduces ChatGPT-specific MCP tools that expose Basic Memory's search and fetch functionality using OpenAI's required tool schema and response format.

Requirements

ChatGPT Plus/Pro Subscription

Required: ChatGPT Plus or Pro subscription

• Free tier does NOT support MCP
• Pro tier includes MCP support

Pricing:

• ChatGPT Plus: $20/month
• ChatGPT Pro: $200/month (includes advanced features)

Developer Mode

Required: ChatGPT Developer Mode

• Access to MCP server configuration
• Ability to add custom MCP servers

Enable Developer Mode:

1. Open ChatGPT settings
2. Navigate to "Advanced" or "Developer" settings
3. Enable "Developer Mode"
4. Restart ChatGPT

Remote MCP Configuration

Important: ChatGPT only supports remote MCP servers

• Cannot use local MCP (like Claude Desktop)
• Requires publicly accessible MCP server
• Basic Memory must be deployed and reachable

How It Works

ChatGPT-Specific Format

OpenAI requires MCP responses in a specific format:

Standard MCP (Claude, etc.):

{
  "results": [...],
  "total": 10
}

ChatGPT MCP:

[
  {
    "type": "text",
    "text": "{\"results\": [...], \"total\": 10}"
  }
]

Key difference: ChatGPT expects content wrapped in [{"type": "text", "text": "..."}] array

Adapter Architecture

ChatGPT Request
    ↓
ChatGPT MCP Tools (chatgpt_tools.py)
    ↓
Standard Basic Memory Tools (search_notes, read_note)
    ↓
Format for ChatGPT
    ↓
[{"type": "text", "text": "{...json...}"}]
    ↓
ChatGPT Response

Available Tools

1. search

Search across the knowledge base.

Tool Definition:

{
  "name": "search",
  "description": "Search for content across the knowledge base",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search query"
      }
    },
    "required": ["query"]
  }
}

Example Request:

{
  "query": "authentication system"
}

Example Response:

[
  {
    "type": "text",
    "text": "{\"results\": [{\"id\": \"auth-design\", \"title\": \"Authentication Design\", \"url\": \"auth-design\"}], \"total_count\": 1, \"query\": \"authentication system\"}"
  }
]

Parsed JSON:

{
  "results": [
    {
      "id": "auth-design",
      "title": "Authentication Design",
      "url": "auth-design"
    }
  ],
  "total_count": 1,
  "query": "authentication system"
}

2. fetch

Fetch full contents of a document.

Tool Definition:

{
  "name": "fetch",
  "description": "Fetch the full contents of a search result document",
  "inputSchema": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "description": "Document identifier"
      }
    },
    "required": ["id"]
  }
}

Example Request:

{
  "id": "auth-design"
}

Example Response:

[
  {
    "type": "text",
    "text": "{\"id\": \"auth-design\", \"title\": \"Authentication Design\", \"text\": \"# Authentication Design\\n\\n...\", \"url\": \"auth-design\", \"metadata\": {\"format\": \"markdown\"}}"
  }
]

Parsed JSON:

{
  "id": "auth-design",
  "title": "Authentication Design",
  "text": "# Authentication Design\n\n...",
  "url": "auth-design",
  "metadata": {
    "format": "markdown"
  }
}

Configuration

Remote MCP Server Setup

Option 1: Deploy to Cloud

# Deploy Basic Memory to cloud provider
# Ensure publicly accessible

# Example: Deploy to Fly.io
fly deploy

# Get URL
export MCP_SERVER_URL=https://your-app.fly.dev

Option 2: Use ngrok for Testing

# Start Basic Memory locally
bm mcp --port 8000

# Expose via ngrok
ngrok http 8000

# Get public URL
# → https://abc123.ngrok.io

ChatGPT MCP Configuration

In ChatGPT Developer Mode:

{
  "mcpServers": {
    "basic-memory": {
      "url": "https://your-server.com/mcp",
      "apiKey": "your-api-key-if-needed"
    }
  }
}

Environment Variables (if using auth):

export BASIC_MEMORY_API_KEY=your-secret-key

Usage Examples

Search Workflow

User asks ChatGPT:

"Search my knowledge base for authentication notes"

ChatGPT internally calls:

{
  "tool": "search",
  "arguments": {
    "query": "authentication notes"
  }
}

Basic Memory responds:

[{
  "type": "text",
  "text": "{\"results\": [{\"id\": \"auth-design\", \"title\": \"Auth Design\", \"url\": \"auth-design\"}, {\"id\": \"oauth-setup\", \"title\": \"OAuth Setup\", \"url\": \"oauth-setup\"}], \"total_count\": 2, \"query\": \"authentication notes\"}"
}]

ChatGPT displays:

I found 2 documents about authentication:

1. Auth Design
2. OAuth Setup

Fetch Workflow

User asks ChatGPT:

"Show me the Auth Design document"

ChatGPT internally calls:

{
  "tool": "fetch",
  "arguments": {
    "id": "auth-design"
  }
}

Basic Memory responds:

[{
  "type": "text",
  "text": "{\"id\": \"auth-design\", \"title\": \"Auth Design\", \"text\": \"# Auth Design\\n\\n## Overview\\n...full content...\", \"url\": \"auth-design\", \"metadata\": {\"format\": \"markdown\"}}"
}]

ChatGPT displays:

Here's the Auth Design document:

Auth Design

Overview

...

Response Schema

Search Response

{
  results: Array<{
    id: string,        // Document permalink
    title: string,     // Document title
    url: string        // Document URL/permalink
  }>,
  total_count: number, // Total results found
  query: string        // Original query echoed back
}

Fetch Response

{
  id: string,          // Document identifier
  title: string,       // Document title
  text: string,        // Full markdown content
  url: string,         // Document URL/permalink
  metadata: {
    format: string     // "markdown"
  }
}

Error Response

{
  results: [],         // Empty for search
  error: string,       // Error type
  error_message: string // Error details
}

Differences from Standard Tools

ChatGPT Tools vs Standard MCP Tools

Feature	ChatGPT Tools	Standard Tools
Tool Names	search, fetch	search_notes, read_note
Response Format	[{"type": "text", "text": "..."}]	Direct JSON
Parameters	Minimal (query, id)	Rich (project, page, filters)
Project Selection	Automatic	Explicit or default_project_mode
Pagination	Fixed (10 results)	Configurable
Error Handling	JSON error objects	Direct error messages

Automatic Defaults

ChatGPT tools use sensible defaults:

# search tool defaults
page = 1
page_size = 10
search_type = "text"
project = None  # Auto-resolved

# fetch tool defaults
page = 1
page_size = 10
project = None  # Auto-resolved

Project Resolution

Automatic Project Selection

ChatGPT tools use automatic project resolution:

1. CLI constraint (if --project flag used)
2. default_project_mode (if enabled in config)
3. Error if no project can be resolved

Recommended Setup:

// ~/.basic-memory/config.json
{
  "default_project": "main",
  "default_project_mode": true
}

This ensures ChatGPT tools work without explicit project parameters.

Error Handling

Search Errors

[{
  "type": "text",
  "text": "{\"results\": [], \"error\": \"Search failed\", \"error_details\": \"Project not found\"}"
}]

Fetch Errors

[{
  "type": "text",
  "text": "{\"id\": \"missing-doc\", \"title\": \"Fetch Error\", \"text\": \"Failed to fetch document: Not found\", \"url\": \"missing-doc\", \"metadata\": {\"error\": \"Fetch failed\"}}"
}]

Common Errors

No project found:

{
  "error": "Project required",
  "error_message": "No project specified and default_project_mode not enabled"
}

Document not found:

{
  "id": "doc-123",
  "title": "Document Not Found",
  "text": "# Note Not Found\n\nThe requested document 'doc-123' could not be found",
  "metadata": {"error": "Document not found"}
}

Deployment Patterns

Production Deployment

1. Deploy to Cloud:

# Docker deployment
docker build -t basic-memory .
docker run -p 8000:8000 \
  -e BASIC_MEMORY_API_URL=https://api.basicmemory.cloud \
  basic-memory mcp --port 8000

# Or use managed hosting
fly deploy

2. Configure ChatGPT:

{
  "mcpServers": {
    "basic-memory": {
      "url": "https://your-app.fly.dev/mcp"
    }
  }
}

3. Enable default_project_mode:

{
  "default_project_mode": true,
  "default_project": "main"
}

Development/Testing

1. Use ngrok:

# Terminal 1: Start MCP server
bm mcp --port 8000

# Terminal 2: Expose with ngrok
ngrok http 8000
# → https://abc123.ngrok.io

2. Configure ChatGPT:

{
  "mcpServers": {
    "basic-memory-dev": {
      "url": "https://abc123.ngrok.io/mcp"
    }
  }
}

Limitations

ChatGPT-Specific Constraints

1. Remote only - Cannot use local MCP server
2. No streaming - Results returned all at once
3. Fixed pagination - 10 results per search
4. Simplified parameters - Cannot specify advanced filters
5. No project selection - Must use default_project_mode
6. Subscription required - ChatGPT Plus/Pro only

Workarounds

For more results:

• Refine search query
• Use fetch to get full documents
• Deploy multiple searches

For project selection:

• Enable default_project_mode
• Or deploy separate instances per project

For advanced features:

• Use Claude Desktop with full MCP tools
• Or use Basic Memory CLI directly

Troubleshooting

ChatGPT Can't Connect

Problem: ChatGPT shows "MCP server unavailable"

Solutions:

1. Verify server is publicly accessible

   curl https://your-server.com/mcp/health
   

2. Check firewall/security groups

3. Verify HTTPS (not HTTP)

4. Check API key if using auth

No Results Returned

Problem: Search returns empty results

Solutions:

1. Check default_project_mode enabled

   {"default_project_mode": true}
   

2. Verify data is synced

   bm sync --project main
   

3. Test search locally

   bm tools search --query "test"
   

Format Errors

Problem: ChatGPT shows parsing errors

Check response format:

# Must be wrapped array
[{"type": "text", "text": "{...json...}"}]

# NOT direct JSON
{"results": [...]}

Developer Mode Not Available

Problem: Can't find Developer Mode in ChatGPT

Solution:

• Ensure ChatGPT Plus/Pro subscription
• Check for feature rollout (may not be available in all regions)
• Contact OpenAI support

Best Practices

1. Enable default_project_mode

{
  "default_project_mode": true,
  "default_project": "main"
}

2. Use Cloud Deployment

Don't rely on ngrok for production:

# Production deployment
fly deploy
# or
railway up
# or
vercel deploy

3. Monitor Usage

# Enable logging
export BASIC_MEMORY_LOG_LEVEL=INFO

# Monitor requests
tail -f /var/log/basic-memory/mcp.log

4. Secure Your Server

# Use API key authentication
export BASIC_MEMORY_API_KEY=secret

# Restrict CORS
export BASIC_MEMORY_ALLOWED_ORIGINS=https://chatgpt.com

5. Test Locally First

# Test with curl
curl -X POST https://your-server.com/mcp/tools/search \
  -H "Content-Type: application/json" \
  -d '{"query": "test"}'

Comparison with Claude Desktop

Feature	ChatGPT	Claude Desktop
MCP Mode	Remote only	Local or Remote
Tools	2 (search, fetch)	17+ (full suite)
Response Format	OpenAI-specific	Standard MCP
Project Support	Default only	Full multi-project
Subscription	Plus/Pro required	Free (Claude)
Configuration	Developer mode	Config file
Performance	Network latency	Local (instant)

Recommendation: Use Claude Desktop for full features, ChatGPT for convenience

See Also

• ChatGPT MCP documentation: https://platform.openai.com/docs/mcp
• default-project-mode.md - Required for ChatGPT tools
• cloud-mode-usage.md - Deploying MCP to cloud
• Standard MCP tools documentation