MCP Server

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

How it works: RA-OS 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

Start RA-OS: npm run dev
Configure your AI assistant (see below)
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-OS installation.

Note: RA-OS 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"

Make sure RA-OS is running: npm run dev
Check the port isn't blocked: lsof -i :44145
Verify the server started: check terminal output

"Tools not showing"

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

"Permission denied"

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

3.0 KiB Raw Blame History