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

MCP Server

Connect Claude Code and other AI assistants to your knowledge base.

How it works: RA-OS includes an MCP (Model Context Protocol) server. This lets any MCP-compatible assistant — like Claude Code — search your knowledge graph, add new knowledge, and manage your graph. Everything stays local.

---

Quick Start (Recommended)

The easiest way is using the npm package:

{
  "mcpServers": {
    "ra-h": {
      "command": "npx",
      "args": ["ra-h-mcp-server"]
    }
  }
}

Add this to your ~/.claude.json (Claude Code) or Claude Desktop settings.

Requirements:

• Node.js 18+ installed

That's it. The database is created automatically on first connection. No need to keep RA-OS running.

---

Alternative: Local Development

If you're developing RA-OS and want to use the local server:

Standalone (No Web App Required)

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

First install dependencies:

cd apps/mcp-server-standalone
npm install

HTTP Transport (Web App Required)

If you want real-time UI updates when nodes are created:

1. Start RA-OS: npm run dev
2. Configure:

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

---

Available Tools

Tool	Description
getContext	Get graph overview — stats, contexts, hub nodes, dimensions, recent activity. Called first automatically.
queryContexts	List contexts, inspect a context, or search contexts by name/description.
createNode	Create a new node (title/source/dimensions)
queryNodes	Search existing nodes by keyword
updateNode	Update an existing node
getNodesById	Get nodes by ID
createEdge	Create relationship between nodes
updateEdge	Update an edge explanation
queryEdge	Query existing edges
queryDimensions	List all dimensions
createDimension	Create a new dimension
updateDimension	Update/rename dimension
deleteDimension	Delete a dimension
listSkills	List available skills
readSkill	Read a skill by name
writeSkill	Create or update a custom skill
deleteSkill	Delete a custom skill
searchContentEmbeddings	Search extracted source content
sqliteQuery	Run read-only SQL queries

---

What to Expect

Once connected, the MCP server instructs Claude to:

1. Call getContext first to orient itself (contexts, hub nodes, dimensions, stats, available skills)
2. Proactively capture knowledge — when a new insight, decision, person, or reference surfaces, it proposes a specific node (title, dimensions, description) so you can approve with minimal friction
3. Read skills for complex tasks — skills provide reusable procedural instructions for graph operations and workflows
4. Search before creating to avoid duplicates

You don't need to ask Claude to use your knowledge base — it will offer when it spots something worth saving.

---

Example Usage

Once connected, you can ask your AI assistant:

"What's in my knowledge graph?"
"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"

---

Key Files

File	Purpose
apps/mcp-server-standalone/	Standalone server (direct SQLite, recommended)
apps/mcp-server/server.js	HTTP MCP server
apps/mcp-server/stdio-server.js	STDIO bridge to HTTP server

---

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

---

Troubleshooting

"Database not found"

The MCP server auto-creates the database on first connection (v1.1.0+). If you're on an older version, run RA-OS once to create it:

npm run dev

"Tools not showing" (npm package)

1. Make sure Node.js 18+ is installed: node --version
2. Try running manually: npx ra-h-mcp-server
3. Restart Claude Code

"Connection refused" (HTTP method)

1. Make sure RA-OS is running: npm run dev
2. Check the port: lsof -i :44145