MCP Server Setup

Overview

Codaph provides a Model Context Protocol (MCP) server that exposes Codaph project data to Claude Code and other MCP-compatible clients. The MCP server runs over stdio and provides tools for:

Listing Codaph projects
Querying project status
Browsing sessions and contributors
Reading timeline events
Getting diff summaries

Quick Setup (Recommended)

For personal use, user-scope configuration is recommended:

codaph mcp setup claude --scope user --run

This command:

Generates the correct claude mcp add command
Executes it immediately with --run
Adds Codaph to ~/.claude.json (user scope)

Why user scope? One setup works across all repos. Codaph MCP tools accept cwd or project_path parameters to target specific projects.

Manual Setup

Get Setup Command

codaph mcp setup claude --scope user

Output:

Recommended command:
  claude mcp add codaph codaph mcp

Tip: add `--run` to execute it for you
Why user scope: one setup works across repos

Execute Command

codaph mcp setup claude --scope user --run
# Or copy/paste the command:
claude mcp add codaph codaph mcp

Verify Installation

Check ~/.claude.json:

{
  "mcpServers": {
    "codaph": {
      "type": "stdio",
      "command": "codaph",
      "args": ["mcp"]
    }
  }
}

Project-Scope Setup

For team/shared configurations, use project scope:

codaph mcp setup claude --scope project --cwd /path/to/repo

This creates .mcp.json in the project root. Share it via git:

{
  "mcpServers": {
    "codaph": {
      "type": "stdio",
      "command": "codaph",
      "args": ["mcp"]
    }
  }
}

codaph init also writes a template at .codaph/mcp/claude-code.json for manual merging.

Available MCP Tools

From src/mcp-server.ts:197-451:

Project Management

codaph_projects_list

Description: List Codaph projects in the local registry with saved provider/automation settings.Input: NoneOutput:

{
  "count": 2,
  "lastProjectPath": "/home/user/project",
  "projects": [
    {
      "cwd": "/home/user/project",
      "repoId": "owner/repo",
      "initialized": true,
      "exists": true,
      "isLast": true,
      "mubitProjectId": "owner/repo",
      "mubitRunScope": "project",
      "agentProviders": ["codex", "claude-code"],
      "automation": { "enabled": true, "gitPostCommit": true }
    }
  ]
}

codaph_projects_add

Description: Add a project path to the Codaph local project registry and set it as current.Input:

{
  "path": "/absolute/or/relative/path"
}

Output:

{
  "addedPath": "/home/user/project",
  "count": 3,
  "lastProjectPath": "/home/user/project",
  "projects": ["/home/user/project", ...]
}

codaph_projects_set_last

Description: Set the current/last project used by Codaph MCP tool defaults.Input:

{
  "path": "/path/to/project"
}

Output:

{
  "lastProjectPath": "/path/to/project",
  "projects": [...]
}

Status & Sync

codaph_status

Description: Return Codaph sync/automation status for a project (same data as codaph status --json).Input:

{
  "cwd": "/path/to/project",  // optional
  "repoId": "owner/repo"       // optional
}

Output:

{
  "cwd": "/home/user/project",
  "repoId": "owner/repo",
  "agentProviders": ["codex"],
  "automation": {
    "enabled": true,
    "gitPostCommit": true,
    "agentComplete": true
  },
  "localPush": {
    "lastSuccessAt": "2026-03-03T10:00:00.000Z",
    "lastImportedEvents": 42
  },
  "remote": {
    "lastSuccessAt": "2026-03-03T10:05:00.000Z",
    "receivedTimelineCount": 100
  }
}

Session Browsing

codaph_sessions_list

Description: List captured sessions from the local Codaph mirror for a project/repo.Input:

{
  "cwd": "/path/to/project",  // optional
  "limit": 200                 // optional, max 5000
}

Output:

{
  "cwd": "/home/user/project",
  "repoId": "owner/repo",
  "total": 15,
  "sessions": [
    {
      "sessionId": "abc123...",
      "from": "2026-03-03T09:00:00.000Z",
      "to": "2026-03-03T09:30:00.000Z",
      "eventCount": 42,
      "threadCount": 1
    }
  ],
  "truncated": false
}

codaph_contributors_list

Description: List contributors/actors in the local Codaph mirror, optionally filtered to a session.Input:

{
  "cwd": "/path/to/project",      // optional
  "sessionId": "abc123...",        // optional
  "limit": 200                     // optional
}

Output:

{
  "repoId": "owner/repo",
  "sessionId": "abc123...",
  "total": 3,
  "contributors": [
    {
      "actorId": "alice",
      "eventCount": 20
    }
  ]
}

Timeline & Events

codaph_timeline_get

Description: Read timeline events from the local Codaph mirror (supports repo/session/thread/actor/time filters).Input:

{
  "cwd": "/path/to/project",           // optional
  "sessionId": "abc123...",             // optional filter
  "threadId": "thread-1",               // optional filter
  "actorId": "alice",                   // optional filter
  "from": "2026-03-03T09:00:00.000Z",   // optional ISO timestamp
  "to": "2026-03-03T10:00:00.000Z",     // optional ISO timestamp
  "itemType": "prompt.submitted",       // optional filter
  "offset": 0,                          // optional pagination
  "limit": 200,                         // optional, max 1000
  "includePayload": true                // optional, default true
}

Output:

{
  "repoId": "owner/repo",
  "filter": { "sessionId": "abc123..." },
  "offset": 0,
  "limit": 200,
  "total": 42,
  "returned": 42,
  "truncated": false,
  "events": [
    {
      "eventId": "evt_...",
      "source": "codex_sdk",
      "repoId": "owner/repo",
      "actorId": "alice",
      "sessionId": "abc123...",
      "threadId": "thread-1",
      "ts": "2026-03-03T09:15:00.000Z",
      "eventType": "prompt.submitted",
      "payload": { "item": { "text": "add tests" } }
    }
  ]
}

Diff & Changes

codaph_diff_summary

Description: Summarize file changes for a Codaph session from the local mirror.Input:

{
  "sessionId": "abc123...",          // required
  "cwd": "/path/to/project",         // optional
  "pathFilter": "src/"               // optional
}

Output:

{
  "repoId": "owner/repo",
  "sessionId": "abc123...",
  "pathFilter": "src/",
  "count": 5,
  "files": [
    {
      "path": "src/auth.ts",
      "kinds": ["update"],
      "occurrences": 3
    }
  ]
}

Tool Usage Patterns

Discover Projects

// List all Codaph projects
const projects = await codaph_projects_list();

// Add current working directory
const added = await codaph_projects_add({ path: process.cwd() });

// Set active project
const updated = await codaph_projects_set_last({ path: "/path/to/project" });

Check Project Status

// Get status for current project
const status = await codaph_status({ cwd: "/path/to/project" });

// List recent sessions
const sessions = await codaph_sessions_list({ 
  cwd: "/path/to/project",
  limit: 10 
});

Analyze Session

// Get session timeline
const timeline = await codaph_timeline_get({
  sessionId: "abc123...",
  limit: 500
});

// Get file changes
const diff = await codaph_diff_summary({
  sessionId: "abc123...",
  pathFilter: "src/"
});

// List contributors
const contributors = await codaph_contributors_list({
  sessionId: "abc123..."
});

Troubleshooting

MCP Server Not Found

Error: command not found: codaphFix:

Ensure Codaph is installed globally: npm i -g @codaph/codaph

Or use absolute path in .claude.json:

{
  "command": "/path/to/codaph",
  "args": ["mcp"]
}

For Bun source installs:

{
  "command": "bun",
  "args": ["--cwd", "/path/to/codaph", "run", "cli", "mcp"]
}

No Projects Found

Issue: MCP tools return empty project list.Fix:

Run codaph init in your project directory first
Or use codaph_projects_add tool with cwd parameter
Check registry: codaph projects list

Permission Denied

Error: EACCES: permission deniedFix:

Ensure Codaph binary is executable: chmod +x $(which codaph)
Check .codaph/ directory permissions
Verify Claude Code has read access to project directory

Invalid JSON Response

Issue: MCP client shows parse errors.Cause: Codaph MCP server supports both framed (Content-Length) and plain JSON stdio.Fix: Most clients auto-detect. If issues persist:

Check Claude Code version supports MCP 2024-11-05 protocol
Verify no extra output in stdio (check CODAPH_DEBUG env var is unset)
Test MCP server directly: echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | codaph mcp

Advanced Configuration

Custom MCP Server Args

Pass --cwd to default all tools to a specific project:

{
  "mcpServers": {
    "codaph-myproject": {
      "type": "stdio",
      "command": "codaph",
      "args": ["mcp", "--cwd", "/path/to/myproject"]
    }
  }
}

Multiple Projects

{
  "mcpServers": {
    "codaph": {
      "type": "stdio",
      "command": "codaph",
      "args": ["mcp"]
    },
    "codaph-work": {
      "type": "stdio",
      "command": "codaph",
      "args": ["mcp", "--cwd", "/work/monorepo"]
    }
  }
}

Debug Mode

Enable debug logging:

CODAPH_DEBUG=1 codaph mcp

Or in .claude.json:

{
  "mcpServers": {
    "codaph": {
      "type": "stdio",
      "command": "codaph",
      "args": ["mcp"],
      "env": {
        "CODAPH_DEBUG": "1"
      }
    }
  }
}

Protocol Details

From src/mcp-server.ts:14-835:

Protocol Version: 2024-11-05
Transport: stdio (supports both Content-Length framing and line-delimited JSON)
Capabilities: tools only (no resources or prompts)
Server Info:
- Name: codaph
- Version: from package.json
- Instructions: “Codaph MCP exposes local Codaph project registry, status, sessions, timeline, and diff summaries. Pass cwd or project_path to target a repo.”

Tool Result Format

All tools return:

{
  "content": [
    {
      "type": "text",
      "text": "JSON string (truncated if > 64KB)"
    }
  ],
  "structuredContent": { /* full structured data */ }
}

Error Handling

Errors return isError: true:

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Error message"
    }
  ]
}

Get Started

Core Concepts

Guides

Advanced

Help

MCP Server Setup

Overview

Quick Setup (Recommended)

Manual Setup

Project-Scope Setup

Available MCP Tools

Project Management

Status & Sync

Session Browsing

Timeline & Events

Diff & Changes

Tool Usage Patterns

Troubleshooting

Advanced Configuration

Custom MCP Server Args

Multiple Projects

Debug Mode

Protocol Details

Tool Result Format

Error Handling

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Advanced

Help

​Overview

​Quick Setup (Recommended)

​Manual Setup

​Project-Scope Setup

​Available MCP Tools

​Project Management

​Status & Sync

​Session Browsing

​Timeline & Events

​Diff & Changes

​Tool Usage Patterns

​Troubleshooting

​Advanced Configuration

​Custom MCP Server Args

​Multiple Projects

​Debug Mode

​Protocol Details

​Tool Result Format

​Error Handling

Build docs developers (and LLMs) love

Overview

Quick Setup (Recommended)

Manual Setup

Project-Scope Setup

Available MCP Tools

Project Management

Status & Sync

Session Browsing

Timeline & Events

Diff & Changes

Tool Usage Patterns

Troubleshooting

Advanced Configuration

Custom MCP Server Args

Multiple Projects

Debug Mode

Protocol Details

Tool Result Format

Error Handling