CortexFlow

Universal MCP Server for AI-to-AI Task Continuation

📊 Benchmark Results

Performance Metrics (click to expand)

Last updated: 2025-12-28

Summary

Metric	Value
Avg Token Savings	56%
Avg Compression Ratio	5.2x
Peak Memory	116 MB
Avg Ops/Second	95.4K

View Full Benchmark Report

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

Open Settings → MCP Servers
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)

Start HTTP server: cortexflow --http
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: mithungowda.b7411@gmail.com

License

MIT License - see LICENSE

Name		Name	Last commit message	Last commit date
Latest commit History 36 Commits
.github		.github
.husky		.husky
benchmarks		benchmarks
config		config
dist		dist
docs		docs
scripts		scripts
src		src
tests		tests
.editorconfig		.editorconfig
.gitignore		.gitignore
.lintstagedrc		.lintstagedrc
.prettierignore		.prettierignore
.prettierrc		.prettierrc
.typos.toml		.typos.toml
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
commitlint.config.js		commitlint.config.js
eslint.config.js		eslint.config.js
jest.config.js		jest.config.js
package.json		package.json
tsconfig.json		tsconfig.json

Uh oh!

License

mithun50/CortexFlow

Folders and files

Latest commit

History

Repository files navigation

CortexFlow

📊 Benchmark Results

Summary

The Problem

How It Works

Supported AI Clients

Desktop Apps (MCP)

CLI Agents (MCP)

Web/Desktop Apps (HTTP API)

Key Features

Core Capabilities

Unique Features (Not in Competitors)

Alternatives & Comparison

When to Use CortexFlow

Installation

From npm (Recommended)

From Source

Configuration

Claude Code

Claude Desktop

Cursor

VS Code + Continue

Antigravity (Google)

ChatGPT (Custom GPT)

Generic MCP Client

MCP Tools

Context Management

Task Management

Agent Communication

Project Management

Intelligent Features

Webhooks & Events

Templates

Version Control

Audit Trail

Personal Todo/Did Lists

Session Memory

Time Tracking

AI Prompt Templates

Multi-AI Export

Productivity Dashboard

Example Workflow

Step 1: ChatGPT Creates Plan

Step 2: Claude Code Continues

Step 3: Any AI Can Check Progress

HTTP API

Endpoints

Example HTTP Calls

Data Storage

Context Schema

Project Structure

Running

Environment Variables

Security

Documentation

Support the Project

Author

License

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 3

Sponsor this project

Uh oh!

Packages 0

Contributors 2

Packages