raph docs | MCP and agents

Setup command

Generate global or project-scoped MCP config.

raph agents mcp setup --path .
raph agents mcp setup --path . --scope local
raph agents mcp setup --path . --dry-run

The setup command checks whether each supported agent is installed and writes the raph MCP entry for every supported target. By default entries go to each agent's global (user-level) config so all projects pick them up; --scope local writes project files under --path instead. An interactive terminal is prompted for the scope when --scope is omitted.

Terminal sample

opencode=/Users/wchr/.opencode/bin/opencode
claude=/Users/wchr/.local/bin/claude
codex=/Applications/Codex.app/Contents/Resources/codex
cursor=missing
pi=/Users/wchr/.nvm/versions/node/v25.2.1/bin/pi

Default server command

command: raph
args: ["start"]

Tool surface

What agents can do through MCP.

Memory and retrieval

store_memory writes scoped memory with lifecycle metadata, source, writer, revision, tags, and timestamps.
update_memory keeps stable keys current while preserving previous revisions.
deprecate_memory retires stale records instead of deleting unrelated graph nodes.
search_project_knowledge, search_shared_knowledge, and search_global_preferences retrieve scoped memory directly.
hybrid_semantic_search, multi_query_search, and best_vector_match search memory, code, and docs.

Code and documentation

index_codebase defaults to the MCP working directory and replaces existing nodes for that codebase.
crawl_url fetches one page; crawl_website returns compact relevant excerpts with bounded limits.
graph_neighbors expands related graph nodes.

Durable handoff

Make repo memory explicit.

Agents should search project memory at startup, use project scope for repo-specific facts, and write durable decisions before finishing. Project scope can infer scope_id from the current workspace; set project.identity_override when the same repo appears at different checkout paths.

Start-of-task lookup

{
  "tool": "search_project_knowledge",
  "arguments": {
    "query": "release signing CI setup gotchas",
    "limit": 5
  }
}

End-of-task memory

{
  "tool": "store_memory",
  "arguments": {
    "scope_type": "project",
    "knowledge_type": "workflow",
    "memory_key": "release/signing",
    "title": "Release signing workflow",
    "content": "This repo uses minisign signatures, immutable GitHub releases, and verifies release artifacts with `gh release verify`.",
    "source": "conversation",
    "writer_id": "agent:opencode",
    "tags": ["release", "signing", "github"]
  }
}

Good project keys are stable and path-like: repo/setup, release/signing, ci/known-issues, and agent/constraints. Store decisions, setup facts, gotchas, commands, and constraints; avoid global scope unless the memory applies across repositories.

Agent targets

Supported config locations.

Priority 1

OpenCode

Project file: opencode.json

Global file: ~/.config/opencode/opencode.json

Plugin: plugins/raph.ts next to the config, auto-loaded by opencode

Priority 2

Claude Code

Project file: .mcp.json

User file: ~/.claude.json

Priority 3

Codex

Project file: .codex/config.toml

Global file: ~/.codex/config.toml

Priority 4

Cursor

Project file: .cursor/mcp.json

Global file: ~/.cursor/mcp.json

Experimental

Pi

Project file: .pi/mcp.json

Global file: ~/.pi/mcp.json

Config layout

The config differs by file format, not by behavior.

OpenCode

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "raph": {
      "type": "local",
      "command": ["raph", "start"],
      "enabled": true
    }
  }
}

Claude Code

{
  "mcpServers": {
    "raph": {
      "type": "stdio",
      "command": "raph",
      "args": ["start"],
      "env": {}
    }
  }
}

Codex

[mcp_servers.raph]
command = "raph"
args = ["start"]

Cursor / Pi

{
  "mcpServers": {
    "raph": {
      "type": "stdio",
      "command": "raph",
      "args": ["start"],
      "env": {}
    }
  }
}

Connect raph once, then let agents search and store context locally.