ra-h-os/docs/8_mcp.md

MCP Server

How to connect Claude Code and other AI assistants to your knowledge base.

How it works: RA-H Light runs a local MCP (Model Context Protocol) server. This lets any MCP-compatible assistant — like Claude Code — search your notes, add new knowledge, and manage your knowledge graph. Everything stays local; nothing goes to the cloud.

---

Quick Start

1. Start RA-H Light: npm run dev
2. Configure your AI assistant (see below)
3. Use naturally: "Search RA-H for my notes on X" or "Add this to RA-H"

---

Available Tools

Tool	Description
rah_add_node	Create a new node (title/content/dimensions)
rah_search_nodes	Search existing nodes
rah_update_node	Update an existing node
rah_get_nodes	Get nodes by ID
rah_create_edge	Create relationship between nodes
rah_query_edges	Query existing edges
rah_update_edge	Update edge metadata
rah_create_dimension	Create a new dimension
rah_update_dimension	Update dimension description
rah_delete_dimension	Delete a dimension
rah_search_embeddings	Semantic search across embeddings

---

Claude Code Configuration

Add to your ~/.claude.json or Claude Code settings:

{
  "mcpServers": {
    "ra-h": {
      "command": "node",
      "args": ["/path/to/ra-h_os/apps/mcp-server/stdio-server.js"]
    }
  }
}

Replace /path/to/ra-h_os with the actual path to your RA-H Light installation.

Note: RA-H Light must be running (npm run dev) for the MCP server to work.

---

HTTP Transport

For assistants that support HTTP transport:

URL: http://127.0.0.1:44145/mcp

{
  "mcpServers": {
    "ra-h": {
      "url": "http://127.0.0.1:44145/mcp"
    }
  }
}

To start the HTTP server standalone:

node apps/mcp-server/server.js

---

Example Usage

Once connected, you can ask your AI assistant:

"Search RA-H for what I wrote about product strategy"
"Add this conversation summary to RA-H as a new node"
"Find all nodes with the 'research' dimension"
"Create an edge between node 123 and node 456"
"What are my most connected nodes?"

---

Security

• The MCP server only binds to 127.0.0.1 — localhost only
• No authentication required (local access only)
• All data persisted to ~/Library/Application Support/RA-H/db/rah.sqlite

---

Health Check

curl http://127.0.0.1:44145/status

---

Key Files

File	Purpose
apps/mcp-server/server.js	HTTP MCP server
apps/mcp-server/stdio-server.js	STDIO MCP server (for Claude Code)

---

Troubleshooting

"Connection refused"

1. Make sure RA-H Light is running: npm run dev
2. Check the port isn't blocked: lsof -i :44145
3. Verify the server started: check terminal output

"Tools not showing"

1. Restart your AI assistant after configuring
2. Verify the path in your config is correct
3. Check node apps/mcp-server/stdio-server.js runs without errors

"Permission denied"

1. Make sure the stdio-server.js file is readable
2. Check Node.js is in your PATH