CortexFlow

Universal MCP Server for AI-to-AI Task Continuation

CortexFlow is an MCP (Model Context Protocol) server that enables seamless handoff between AI agents. When you finish planning with ChatGPT, Claude Code can read the context and continue execution - without re-explaining the project.

The Problem

Every time you switch between AI assistants, you lose context:

😫 Without CortexFlow:
┌─────────────────────────────────────────────────────────────┐
│  ChatGPT: "I've designed a plan with 5 tasks..."           │
│     ↓                                                       │
│  [Switch to Claude Code]                                    │
│     ↓                                                       │
│  Claude: "What project? What tasks? Please explain again."  │
│     ↓                                                       │
│  You: *Re-explains everything for the 10th time* 😩         │
└─────────────────────────────────────────────────────────────┘

✅ With CortexFlow:
┌─────────────────────────────────────────────────────────────┐
│  ChatGPT: write_context() → "Plan saved to CortexFlow"      │
│     ↓                                                       │
│  [Switch to Claude Code]                                    │
│     ↓                                                       │
│  Claude: read_context() → "Got it! Continuing task 2..."    │
└─────────────────────────────────────────────────────────────┘

How It Works

┌─────────────────────────────────────────────────────────────────────────┐
│                                                                          │
│   AI Agent A (Planner)              AI Agent B (Executor)               │
│   ┌─────────────────┐               ┌─────────────────┐                 │
│   │    ChatGPT      │               │   Claude Code   │                 │
│   │    Gemini       │               │     Cursor      │                 │
│   │    Qwen         │               │    VS Code      │                 │
│   └────────┬────────┘               └────────┬────────┘                 │
│            │                                  │                          │
│            │  write_context()                 │  read_context()         │
│            │  add_task()                      │  update_task()          │
│            │  add_note()                      │  mark_task_complete()   │
│            │                                  │                          │
│            ▼                                  ▼                          │
│   ┌──────────────────────────────────────────────────────────┐          │
│   │                    CortexFlow MCP Server                  │          │
│   │                                                           │          │
│   │   ┌─────────────────────────────────────────────────┐    │          │
│   │   │              Shared Project Context              │    │          │
│   │   │                                                  │    │          │
│   │   │  • Project: "Todo API"                          │    │          │
│   │   │  • Phase: execution                              │    │          │
│   │   │  • Tasks: [Setup, Models, Routes, Tests]        │    │          │
│   │   │  • Notes: "Use Express + TypeScript"            │    │          │
│   │   │                                                  │    │          │
│   │   └─────────────────────────────────────────────────┘    │          │
│   │                                                           │          │
│   │   Transport: stdio (MCP) | HTTP API                      │          │
│   └──────────────────────────────────────────────────────────┘          │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

Supported AI Clients

Desktop Apps (MCP)

| App | Platform | Config | | ------------------ | --------------------- | ---------------------------- | | Claude Desktop | macOS, Windows, Linux | claude_desktop_config.json | | Cursor | macOS, Windows, Linux | Settings → MCP | | VS Code + Continue | macOS, Windows, Linux | .continue/config.json | | Antigravity | macOS, Windows, Linux | MCP settings | | Zed | macOS, Linux | Settings | | Jan | macOS, Windows, Linux | MCP settings | | LM Studio | macOS, Windows, Linux | MCP settings | | Msty | macOS, Windows, Linux | MCP settings |

CLI Agents (MCP)

| Agent | Transport | Config | | -------------- | --------- | -------------------- | | Claude Code | stdio | ~/.claude/mcp.json | | Gemini CLI | stdio | MCP config | | Qwen CLI | stdio | MCP config | | Aider | stdio | MCP config | | Any MCP client | stdio | Generic config |

Web/Desktop Apps (HTTP API)

| App | Integration | Status | | --------------------- | ------------------ | ------ | | ChatGPT (Web/Desktop) | Custom GPT Actions | ✅ | | Gemini (Web) | Function calling | ✅ | | Typing Mind | Plugin/HTTP | ✅ | | LibreChat | External tool | ✅ | | Open WebUI | HTTP tools | ✅ | | Any HTTP client | REST API | ✅ |

Key Features

Core Capabilities

| Feature | Description | | ---------------------- | ----------------------------------------------------------------------- | | Dual Transport | MCP (stdio) + HTTP REST API - works with any client | | 14+ Client Configs | Ready-to-use configs for Claude, Cursor, VS Code, ChatGPT, Gemini, etc. | | OpenAPI Spec | Auto-generated spec for ChatGPT Custom GPT Actions | | Agent Roles | Planner, Executor, Reviewer - track who did what | | Note Categories | General, Decision, Blocker, Insight - structured communication | | Task Dependencies | Define which tasks depend on others | | Project Phases | Planning → Execution → Review → Completed lifecycle |

Unique Features (Not in Competitors)

| Feature | Description | Status | | --------------------------- | -------------------------------------------------------- | ------------ | | Agent Attribution | Every action tracked with agent role + timestamp | ✅ Available | | Blocker Detection | Tasks marked as "blocked" with reason tracking | ✅ Available | | Priority System | 5-level priority (1=critical to 5=low) | ✅ Available | | Version Tracking | Auto-incrementing version on every change | ✅ Available | | Dependency Graph | Task dependencies for execution ordering | ✅ Available | | Multi-Project | Switch between multiple projects seamlessly | ✅ Available | | Project Snapshots | Version control with rollback capability | ✅ Available | | Agent Analytics | Track completion rates per agent | ✅ Available | | Webhook Events | Notify external systems on task completion | ✅ Available | | Workflow Templates | Pre-built templates (Bug Fix, Feature, Refactor, Review) | ✅ Available | | Critical Path Analysis | Identify bottlenecks and optimize task scheduling | ✅ Available | | Smart Priority Queue | AI-optimized task ordering based on dependencies | ✅ Available | | Context Compression | 40-60% token reduction for efficient AI-to-AI transfer | ✅ Available | | Project Health Score | 0-100 score with risk analysis and recommendations | ✅ Available | | Batch Operations | Execute multiple operations atomically | ✅ Available | | Intelligent Suggestions | AI-powered recommendations for project health | ✅ Available | | Audit Logging | Complete change history with filtering | ✅ Available | | Personal Todo/Did Lists | Personal task tracking with reflections & goals | ✅ Available | | Session Memory | Persistent key-value storage across sessions | ✅ Available | | Time Tracking | Track time per task with statistics | ✅ Available | | AI Prompt Templates | Pre-built prompts for planning, debugging, review | ✅ Available | | Multi-AI Export | Export context for Claude, Gemini, ChatGPT, Cursor | ✅ Available | | Productivity Dashboard | Daily digest, streaks, productivity stats | ✅ Available |

Alternatives & Comparison

CortexFlow isn't the only solution. Here's how it compares:

| Feature | CortexFlow | mcp-handoff-server | OpenMemory MCP | Context Sync | | -------------------- | ------------------ | ----------------------------------------------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | Transport | MCP + HTTP | MCP only | MCP only | MCP only | | ChatGPT Support | ✅ OpenAPI Actions | ❌ | ❌ | ❌ | | Task Management | ✅ Full CRUD | ✅ Handoff docs | ❌ Memory focus | ✅ Todo system | | Agent Roles | ✅ 3 roles | ❌ | ❌ | ❌ | | Dependencies | ✅ Task deps | ❌ | ❌ | ❌ | | Note Categories | ✅ 4 types | ❌ | ❌ | ❌ | | Storage | JSON files | JSON files | SQLite | SQLite | | Setup Complexity | Simple | Simple | Moderate | Moderate | | Primary Focus | Task handoff | Doc handoff | Memory/RAG | Code context |

When to Use CortexFlow

✅ Use CortexFlow if you need:

• HTTP API for ChatGPT/web clients
• Structured task management with priorities
• Agent role tracking (who did what)
• Simple JSON storage you can inspect
• Minimal dependencies

❌ Consider alternatives if you need:

• Semantic memory/RAG (OpenMemory)
• Deep code understanding (Context Sync)
• Complex handoff documents (mcp-handoff-server)

Installation

From npm (Recommended)

# Install globally
npm install -g cortexflow

# Or use directly with npx
npx cortexflow

From Source

git clone https://github.com/mithun50/CortexFlow
cd CortexFlow
npm install
npm run build

Configuration

Claude Code

Add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "cortexflow": {
      "command": "npx",
      "args": ["-y", "cortexflow"]
    }
  }
}

Or add to project .mcp.json for project-specific config.

Claude Desktop

Add to config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/claude-desktop/config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "cortexflow": {
      "command": "npx",
      "args": ["-y", "cortexflow"]
    }
  }
}

Cursor

1. Open Settings → MCP Servers
2. Add new server:
   • Name: cortexflow
   • Command: npx -y cortexflow

VS Code + Continue

Add to .continue/config.json:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "cortexflow"]
        }
      }
    ]
  }
}

Antigravity (Google)

Add to ~/.gemini/antigravity/mcp_config.json:

{
  "mcpServers": {
    "cortexflow": {
      "command": "npx",
      "args": ["-y", "cortexflow"]
    }
  }
}

Or access via: Agent Options (...) → MCP Servers → Manage MCP Servers → View raw config

For HTTP mode (remote):

{
  "mcpServers": {
    "cortexflow": {
      "serverUrl": "http://localhost:3210"
    }
  }
}

Note: Antigravity uses serverUrl instead of url for HTTP-based MCP servers.

ChatGPT (Custom GPT)

1. Start HTTP server: cortexflow --http
2. Create Custom GPT with Actions using OpenAPI spec at http://localhost:3210/openapi.json

Generic MCP Client

For any MCP-compatible client, use stdio transport:

• Command: npx
• Args: ["-y", "cortexflow"]

MCP Tools

Context Management

| Tool | Description | | --------------- | -------------------------------------------------- | | read_context | Read active project: tasks, notes, phase, metadata | | write_context | Create new project with initial tasks |

Task Management

| Tool | Description | | -------------------- | ------------------------------- | | add_task | Add a new task to the project | | update_task | Update task status or add notes | | mark_task_complete | Mark a task as completed |

Agent Communication

| Tool | Description | | ----------- | ---------------------------------------------------------- | | add_note | Add a note for other AI agents | | set_phase | Update project phase (planning/execution/review/completed) |

Project Management

| Tool | Description | | -------------------- | ----------------------------------------------------- | | list_projects | List all projects | | set_active_project | Switch active project | | delete_project | Delete a project | | get_analytics | Get project analytics (completion rates, agent stats) | | export_project | Export project to Markdown format | | clone_project | Clone a project with optional task reset |

Intelligent Features

| Tool | Description | | ------------------- | ----------------------------------------------------- | | get_critical_path | Analyze task dependencies, find bottlenecks | | get_smart_queue | Get AI-prioritized task execution order | | compress_context | Get token-efficient compressed representation | | get_health_score | Get 0-100 health score with risks and recommendations | | batch_operations | Execute multiple operations atomically | | get_suggestions | Get AI-powered task suggestions |

Webhooks & Events

| Tool | Description | | ------------------ | -------------------------------------------------- | | register_webhook | Subscribe to project events (task.completed, etc.) | | list_webhooks | List all registered webhooks | | delete_webhook | Unsubscribe a webhook |

Templates

| Tool | Description | | ---------------------- | ----------------------------------------------------------------- | | list_templates | List available project templates | | create_from_template | Create project from template (bug-fix, feature, refactor, review) |

Version Control

| Tool | Description | | ------------------ | --------------------------------- | | create_snapshot | Save project state for rollback | | list_snapshots | List all snapshots for a project | | restore_snapshot | Restore project to previous state |

Audit Trail

| Tool | Description | | --------------- | ------------------------------------------ | | get_audit_log | Get complete change history with filtering |

Personal Todo/Did Lists

| Tool | Description | | ------------------------ | ----------------------------------------------- | | add_personal_todo | Add personal todo (separate from project tasks) | | list_personal_todos | List personal todos with filtering | | complete_personal_todo | Complete todo and move to "did" list | | list_dids | View completed items with reflections | | set_goals | Set daily/weekly goals | | get_goals | Get current goals |

Session Memory

| Tool | Description | | --------------- | -------------------------------------------------- | | remember | Store key-value pairs that persist across sessions | | recall | Retrieve stored memory by key | | list_memories | List all memories with filtering | | forget | Remove a specific memory |

Time Tracking

| Tool | Description | | --------------------- | ------------------------------- | | start_time_tracking | Start tracking time for a task | | stop_time_tracking | Stop tracking and log duration | | get_time_stats | Get time statistics per project |

AI Prompt Templates

| Tool | Description | | ----------------------- | ------------------------------------------------------ | | list_prompt_templates | List available prompt templates | | generate_prompt | Generate filled prompt from template + project context |

Multi-AI Export

| Tool | Description | | ------------------ | --------------------------------------------------- | | export_claude_md | Export for Claude, Gemini, ChatGPT, Cursor, Copilot |

Productivity Dashboard

| Tool | Description | | ------------------------ | --------------------------------- | | get_daily_digest | Daily productivity summary | | get_productivity_stats | Weekly/monthly stats with streaks |

Example Workflow

Step 1: ChatGPT Creates Plan

User to ChatGPT: "Plan a REST API for todo management"

ChatGPT calls write_context:

{
  "name": "Todo API",
  "description": "RESTful API with CRUD operations for todos",
  "phase": "planning",
  "tasks": [
    { "title": "Setup Express server", "description": "Initialize with TypeScript" },
    { "title": "Create Todo model", "description": "id, title, completed, createdAt" },
    { "title": "Implement CRUD routes", "description": "POST, GET, PUT, DELETE" },
    { "title": "Add input validation", "description": "Use Zod for validation" }
  ]
}

ChatGPT calls add_note:

{
  "content": "Start with task 1-2 in parallel. Use in-memory storage for MVP.",
  "agent": "planner",
  "category": "decision"
}

ChatGPT calls set_phase:

{ "phase": "execution" }

Step 2: Claude Code Continues

User to Claude Code: "Continue the Todo API project"

Claude Code calls read_context and receives:

Project: Todo API
Phase: execution
Tasks: 0/4 completed, 4 pending

Tasks:
  [a1b2] PENDING: Setup Express server
  [c3d4] PENDING: Create Todo model
  [e5f6] PENDING: Implement CRUD routes
  [g7h8] PENDING: Add input validation

Recent Notes:
  [planner/decision] Start with task 1-2 in parallel. Use in-memory storage for MVP.

Claude Code understands the full context and starts implementation:

// update_task
{ "task_id": "a1b2", "status": "in_progress" }

After completing:

// mark_task_complete
{ "task_id": "a1b2", "note": "Express server with TypeScript, CORS, helmet configured" }

Step 3: Any AI Can Check Progress

Any connected AI can call read_context to see current state:

• Which tasks are done
• What notes were left
• Current project phase
• Full history of updates

HTTP API

For non-MCP clients, start HTTP server:

cortexflow --http

Endpoints

# Core
GET  /health                    Health check
GET  /openapi.json              OpenAPI spec (for ChatGPT Actions)

# Projects
GET  /api/context               Read active project
PUT  /api/context               Update project metadata
GET  /api/projects              List all projects
POST /api/projects              Create new project
GET  /api/projects/:id          Get specific project
DELETE /api/projects/:id        Delete project
POST /api/active                Set active project
POST /api/clone                 Clone a project

# Tasks
GET  /api/tasks                 List tasks
POST /api/tasks                 Add task
PUT  /api/tasks/:id             Update task
POST /api/tasks/:id/complete    Complete task

# Notes & Analytics
GET  /api/notes                 List notes
POST /api/notes                 Add note
GET  /api/analytics             Get project analytics
GET  /api/export                Export project (markdown/json)

# Intelligent Features
GET  /api/critical-path         Critical path analysis
GET  /api/smart-queue           AI-prioritized task queue
GET  /api/compress              Token-efficient context
GET  /api/health-score          Project health score
POST /api/batch                 Batch operations
GET  /api/suggestions           AI suggestions

# Advanced Features
GET  /api/webhooks              List webhooks
POST /api/webhooks              Register webhook
DELETE /api/webhooks/:id        Delete webhook
GET  /api/templates             List templates
POST /api/templates/create      Create from template
GET  /api/snapshots             List snapshots
POST /api/snapshots             Create snapshot
POST /api/snapshots/:id/restore Restore snapshot
GET  /api/audit                 Audit log

# Productivity Features
GET  /api/personal-todos        List personal todos
POST /api/personal-todos        Add personal todo
POST /api/personal-todos/:id/complete  Complete todo
GET  /api/dids                  List completed items
GET  /api/goals                 Get goals
PUT  /api/goals                 Set goals
GET  /api/memory                List memories
POST /api/memory                Remember something
DELETE /api/memory?key=...      Forget memory
POST /api/time-tracking/start   Start time tracking
POST /api/time-tracking/stop    Stop time tracking
GET  /api/time-tracking/stats   Get time stats
GET  /api/prompts               List prompt templates
POST /api/prompts/generate      Generate filled prompt
GET  /api/export-md             Export for AI (claude/gemini/chatgpt/cursor)
GET  /api/digest                Get daily digest
GET  /api/productivity-stats    Get productivity stats

Example HTTP Calls

# Create project
curl -X POST http://localhost:3210/api/projects \
  -H "Content-Type: application/json" \
  -d '{"name":"My Project","description":"Building something"}'

# Read context
curl http://localhost:3210/api/context

# Add task
curl -X POST http://localhost:3210/api/tasks \
  -H "Content-Type: application/json" \
  -d '{"title":"First task","description":"Do the thing"}'

# Complete task
curl -X POST http://localhost:3210/api/tasks/abc123/complete

# Get critical path analysis
curl http://localhost:3210/api/critical-path

# Get smart task queue
curl http://localhost:3210/api/smart-queue?limit=5

# Get project health score
curl http://localhost:3210/api/health-score

# Get compressed context (for AI-to-AI transfer)
curl http://localhost:3210/api/compress

# Create project from template
curl -X POST http://localhost:3210/api/templates/create \
  -H "Content-Type: application/json" \
  -d '{"template_id":"tpl-feature","project_name":"New Feature"}'

# Create snapshot
curl -X POST http://localhost:3210/api/snapshots \
  -H "Content-Type: application/json" \
  -d '{"name":"Before refactor","description":"Backup before changes"}'

# Batch operations
curl -X POST http://localhost:3210/api/batch \
  -H "Content-Type: application/json" \
  -d '{"operations":[
    {"type":"create_task","payload":{"title":"Task 1","description":"First"}},
    {"type":"create_task","payload":{"title":"Task 2","description":"Second"}}
  ]}'

# Add personal todo
curl -X POST http://localhost:3210/api/personal-todos \
  -H "Content-Type: application/json" \
  -d '{"content":"Review PR","priority":2,"tags":["code-review"]}'

# Remember something
curl -X POST http://localhost:3210/api/memory \
  -H "Content-Type: application/json" \
  -d '{"key":"preferred_style","value":"functional","category":"preference"}'

# Export for Claude/Gemini/ChatGPT
curl "http://localhost:3210/api/export-md?format=standard&target=gemini"

# Get daily digest
curl http://localhost:3210/api/digest

# Get productivity stats
curl "http://localhost:3210/api/productivity-stats?period=week"

Data Storage

Projects are stored as JSON files:

~/.cortexflow/
└── data/
    ├── abc123.json      # Project file
    ├── def456.json      # Another project
    └── .active          # Active project ID

Configure with environment variable:

export CORTEXFLOW_DATA_DIR=/custom/path

Context Schema

interface ProjectContext {
  id: string;
  name: string;
  description: string;
  phase: 'planning' | 'execution' | 'review' | 'completed';
  version: number;
  createdAt: string;
  updatedAt: string;
  tasks: Task[];
  notes: AgentNote[];
  tags: string[];
}

interface Task {
  id: string;
  title: string;
  description: string;
  status: 'pending' | 'in_progress' | 'blocked' | 'completed' | 'cancelled';
  priority: number; // 1-5
  assignedTo: 'planner' | 'executor' | 'reviewer' | null;
  notes: string[];
  dependencies: string[];
}

interface AgentNote {
  id: string;
  agent: 'planner' | 'executor' | 'reviewer';
  content: string;
  category: 'general' | 'decision' | 'blocker' | 'insight';
  timestamp: string;
}

Project Structure

cortexflow/
├── src/
│   ├── models.ts       # Data types and schemas
│   ├── storage.ts      # JSON file persistence
│   ├── server.ts       # MCP server (stdio)
│   ├── http-server.ts  # HTTP REST API
│   └── index.ts        # Entry point
├── config/
│   ├── claude-code/    # Claude Code config
│   ├── claude-desktop/ # Claude Desktop config
│   ├── cursor/         # Cursor config
│   ├── vscode/         # VS Code Continue config
│   └── generic-mcp.json
├── package.json
├── tsconfig.json
└── README.md

Running

# MCP server (for Claude Code, Cursor, etc.)
cortexflow

# HTTP server (for ChatGPT, web clients)
cortexflow --http

# Both servers
cortexflow --both

Environment Variables

| Variable | Default | Description | | --------------------- | -------------------- | ---------------- | | CORTEXFLOW_PORT | 3210 | HTTP server port | | CORTEXFLOW_DATA_DIR | ~/.cortexflow/data | Data directory |

Security

• HTTP server binds to localhost only
• No authentication (designed for local use)
• For remote access, use reverse proxy with auth
• Never expose directly to internet

Documentation

• 📖 Full Documentation - Interactive docs website
• 📚 API Reference - MCP tools and HTTP endpoints
• 📘 Usage Guide - Workflows and best practices
• 🤝 Contributing - How to contribute
• 🔒 Security Policy - Reporting vulnerabilities
• 📜 Code of Conduct - Community guidelines

Support the Project

If CortexFlow helps your workflow, consider supporting:

Author

Mithun Gowda B

• GitHub: @mithun50
• Email: [email protected]

License

MIT License - see LICENSE