Skip to main content

​
MCP Server Overview

CodeFire includes a companion Model Context Protocol (MCP) server that exposes your project data to AI coding assistants like Claude Code, Gemini CLI, Codex CLI, and OpenCode.

​
What is the MCP Server?

The CodeFire MCP server (CodeFireMCP) is a standalone executable that implements the Model Context Protocol, allowing AI agents to interact with your CodeFire projects through a standardized interface. Instead of your AI agent starting each session from scratch, it can:
  • See what tasks are in progress
  • Read project notes and context
  • Create and update tasks programmatically
  • Search your codebase semantically
  • Control your browser for testing and debugging
  • Generate images for your project
  • Inspect git status and manage commits

​
The Feedback Loop

CodeFire creates a powerful feedback loop between you, your projects, and your AI agent: 
┌─────────────┐
│   You       │
│  (Human)    │
└──────┬──────┘
       │
       ▼
┌─────────────────────────────┐
│  CodeFire GUI               │
│  - Manage tasks & notes     │
│  - Monitor sessions         │
│  - Browse projects          │
└──────────┬──────────────────┘
           │
           │ Shared SQLite DB
           │ (~/Library/Application Support/CodeFire/codefire.db)
           │
┌──────────▼──────────────────┐
│  CodeFire MCP Server        │
│  - stdio communication      │
│  - Auto-detect project      │
│  - Expose tools to AI       │
└──────────┬──────────────────┘
           │
           ▼
┌─────────────────────────────┐
│  AI Agent                   │
│  (Claude Code, Gemini, etc) │
│  - Read tasks & context     │
│  - Create tasks             │
│  - Search codebase          │
└─────────────────────────────┘
Your AI agent has persistent memory across sessions because it can read what you’ve documented in CodeFire and contribute back to it.

​
Architecture

​
Communication Protocol

The MCP server communicates via stdio (standard input/output) using JSON-RPC 2.0. Your AI CLI tool spawns the CodeFireMCP executable as a subprocess and exchanges messages over stdin/stdout.

​
Shared Database

Both the CodeFire GUI app and the MCP server read from and write to the same SQLite database: 
~/Library/Application Support/CodeFire/codefire.db
The database uses WAL mode (Write-Ahead Logging) to enable safe concurrent access from multiple processes. The MCP server includes a 5-second busy timeout to handle cross-process locking.

​
Project Auto-Detection

When the MCP server starts, it automatically detects which CodeFire project you’re working on by:
  1. Reading the current working directory (where your AI agent was launched)
  2. Querying the database for projects matching that path
  3. Falling back to parent directory matching (so /path/to/project/src matches /path/to/project)
If a project is detected, you can omit the project_id parameter from most tool calls — it will default to the auto-detected project. To check which project was detected: 
# From your AI agent
Use the get_current_project tool

​
Connection Status

The MCP server writes a connection status file to: 
~/Library/Application Support/CodeFire/mcp-connections/<pid>.json
This allows the CodeFire GUI to display a live connection indicator showing:
  • Which project the AI agent is working on
  • The working directory
  • Process ID of the MCP server
The status file is automatically cleaned up when the MCP server exits.

​
Supported CLI Tools

CodeFire’s MCP server works with any tool that supports the Model Context Protocol:
CLI ToolLanguageDeveloper
Claude CodeJavaScript/KotlinAnthropic
Gemini CLIJavaScriptGoogle
Codex CLIPythonOpenAI
OpenCodeJavaScriptSST
Configuration instructions for each tool are in the Setup guide.

​
Tool Categories

The MCP server exposes tools organized into seven categories:

​
Projects

Discover and identify which CodeFire project you’re working with.

​
Tasks

Create, read, update, and manage project tasks and global planner tasks. Add notes to track progress.

​
Notes

Read and write project-level notes for capturing context, architectural decisions, and reference material.

​
Browser

Control CodeFire’s built-in browser: navigate, take snapshots, interact with elements, inspect network requests.

​
Git

Check status, view diffs, stage changes, and create commits directly from your AI agent.

​
Clients

Manage client groups for organizing projects in the sidebar.

​
Images

Generate and edit images using AI, saved directly to your project. See the full list of tools in the Tools Reference.

​
Next Steps

Setup Guide

Configure the MCP server for your AI CLI tool

Tools Reference

Browse all available MCP tools and their parameters

Integration Guide

Learn how to use MCP tools effectively in your workflow

Build docs developers (and LLMs) love

Get started for freeTalk to us