Skip to main content

​
Usage

codaph mcp [serve] [options]
Starts a Model Context Protocol (MCP) server that exposes Codaph’s project registry, session history, timeline, and diff capabilities as tools for AI agents.

​
Options

​
--cwd
string
Default working directory for MCP tool calls. Defaults to current directory.

​
MCP Protocol

The Codaph MCP server implements:
  • Protocol Version: 2024-11-05
  • Transport: stdio with JSON-RPC 2.0
  • Framing: Supports both Content-Length headers and line-delimited JSON

​
Available Tools

​
codaph_projects_list

Lists all Codaph projects in the local registry with saved provider/automation settings. Input Schema: No parameters required Returns: Array of projects with settings and status

​
codaph_projects_add

Adds a project path to the Codaph local project registry. Input Schema:
  • path (string, required): Absolute or relative path to project directory

​
codaph_projects_set_last

Sets the current/last project used by Codaph MCP tool defaults. Input Schema:
  • path (string, required): Path to tracked project

​
codaph_status

Returns Codaph sync/automation status for a project (same as codaph status --json). Input Schema:
  • cwd (string): Working directory
  • project_path (string): Alternative to cwd
  • repoId (string): Repository ID

​
codaph_sessions_list

Lists captured sessions from local Codaph mirror. Input Schema:
  • cwd (string): Working directory
  • repoId (string): Repository ID
  • limit (integer): Max sessions to return (1-5000, default 200)

​
codaph_contributors_list

Lists contributors/actors in the local Codaph mirror. Input Schema:
  • cwd (string): Working directory
  • repoId (string): Repository ID
  • sessionId (string): Optional session filter
  • limit (integer): Max contributors (1-5000, default 200)

​
codaph_timeline_get

Reads timeline events from local Codaph mirror with filtering support. Input Schema:
  • cwd (string): Working directory
  • repoId (string): Repository ID
  • sessionId (string): Filter to session
  • threadId (string): Filter to thread
  • actorId (string): Filter by actor
  • from (string): ISO timestamp lower bound
  • to (string): ISO timestamp upper bound
  • itemType (string): Filter by event type
  • offset (integer): Skip first N events
  • limit (integer): Max events (1-1000, default 200)
  • includePayload (boolean): Include event payloads (default true)

​
codaph_diff_summary

Summarizes file changes for a Codaph session. Input Schema:
  • sessionId (string, required): Session to analyze
  • cwd (string): Working directory
  • repoId (string): Repository ID
  • pathFilter (string): Filter to matching paths

​
Examples

​
Start MCP server

codaph mcp

​
Start with custom default directory

codaph mcp --cwd /path/to/project

​
Test MCP server locally

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | codaph mcp

​
Agent Integration

The MCP server enables agents to:
  1. Query session history - Find relevant past coding sessions
  2. Access timeline events - Review what happened in each session
  3. View file changes - See what files were modified
  4. Manage projects - Switch between different codebases

​
Example Tool Call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "codaph_timeline_get",
    "arguments": {
      "sessionId": "ses_abc123",
      "limit": 50,
      "includePayload": true
    }
  }
}

​
Server Capabilities

{
  "capabilities": {
    "tools": {},
    "resources": {},
    "prompts": {}
  },
  "serverInfo": {
    "name": "codaph",
    "version": "0.1.0"
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us