Getting Started

Connect Claude to domain knowledge bases served by Reasons Service.

What is Reasons Service?

Reasons Service hosts domain knowledge bases built with Reasons Forge and serves them over a REST API, MCP server, and web UI. Each knowledge base contains beliefs with tracked truth values, source documents, and a reason maintenance system that propagates retractions automatically.

Connecting Claude Code

The quickest way to add the MCP server:

claude mcp add reasons-service --transport streamable-http https://ftl.reasonsforge.com/mcp

Then authenticate:

claude mcp login reasons-service

Or add it manually to your project-level or global .claude.json:

{
  "mcpServers": {
    "reasons-service": {
      "type": "streamable-http",
      "url": "https://ftl.reasonsforge.com/mcp"
    }
  }
}

When you first use an MCP tool, Claude Code will open a browser window for OAuth authentication. After signing in with Google, return to Claude Code — the session is saved automatically.

Connecting Claude Desktop

The easiest way is through the UI:

Open Claude Desktop and click Customize (bottom-left)
Go to Connectors
Click Add → Add custom connector
Enter https://ftl.reasonsforge.com/mcp as the Remote MCP server URL
Complete the OAuth sign-in when prompted

Or add it manually to your config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "reasons-service": {
      "url": "https://ftl.reasonsforge.com/mcp"
    }
  }
}

Claude Desktop auto-detects the transport type. Restart Claude Desktop after editing the config file.

Example Prompts

Once connected, try asking Claude:

Prompt	What it does
`List domains`	Shows all available knowledge bases
`List beliefs for my-domain`	Browse beliefs in a knowledge base
`Find issues for my-domain`	Finds gated beliefs blocked by unless-list dependencies
`Explain belief-id in my-domain`	Traces the justification chain for why a belief is IN or OUT
`Deep search about security in my-domain`	IDF-ranked search across beliefs and source documents
`Search for authentication in my-domain`	Full-text search across beliefs, entries, and sources
`What would happen if we retracted belief-id in my-domain?`	Simulates the retraction cascade without modifying data

Available MCP Tools

Tool	Description
`deep_search`	IDF-ranked search across beliefs and source documents — recommended default
`search`	Full-text search across beliefs, entries, and sources
`explain_belief`	Trace why a belief is IN or OUT through the justification chain
`what_if`	Simulate retracting or asserting a belief without modifying data
`find_issues`	Find gated beliefs — OUT because an IN blocker appears in their unless-list
`get_belief`	Full details for a specific belief including justifications and dependents
`list_beliefs`	List beliefs with optional status filter (IN, OUT, or all)
`list_domains`	List available knowledge bases with counts
`list_topics`	Browse topic structure of a knowledge base
`list_entries`	List analysis entries by topic
`get_entry`	Read the full content of an analysis entry

Quick Start (Self-Hosting)

SQLite (simplest)

git clone https://github.com/benthomasson/reasons-service.git
cd reasons-service
uv venv && uv pip install -e .

# Start with SQLite (no PostgreSQL needed)
DATABASE_URL=sqlite+aiosqlite:///reasons.db uv run reasons-service

PostgreSQL + Docker

# Start PostgreSQL with pgvector
docker compose up -d

# Open web UI
open http://localhost:8000

# Import a knowledge base
uv run python scripts/load_reasons_db.py ~/path/to/reasons.db domain-name --domain "Your domain"
uv run python scripts/build_embeddings.py --domain-id <uuid>

Optional dependencies

PostgreSQL support is optional. Install with extras if needed:

uv pip install -e ".[postgres]"    # asyncpg, psycopg, pgvector
uv pip install -e ".[ollama]"      # local model serving via Ollama

Configuration

Variable	Default	Purpose
`DATABASE_URL`	`postgresql+asyncpg://...localhost.../reasons_service`	Async DB connection (use `sqlite+aiosqlite:///file.db` for SQLite)
`GOOGLE_CLOUD_PROJECT`	—	GCP project for Vertex AI (LLM features)
`REASONS_LLM`	`true`	Set `false` for data-only mode (no LLM endpoints)
`REASONS_SERVICE_API_KEY`	—	Static bearer token for API access
`GOOGLE_CLIENT_ID`	—	Google OAuth client ID (enables authentication)
`GOOGLE_CLIENT_SECRET`	—	Google OAuth client secret
`SECRET_KEY`	`dev-insecure-key`	Session cookie signing key — set to a random string in production
`MCP_ISSUER_URL`	`https://reasons.reasonsforge.com/mcp`	MCP OAuth issuer URL (set to your domain's `/mcp` path)
`MCP_BASE_URL`	`http://localhost:8000`	URL that MCP tools use for internal API calls
`REASONS_HUB_MODE`	`false`	Public hub mode — disables login and shows only public domains

REST API

# Search a knowledge base
curl localhost:8000/api/domains/{id}/search?q=query+terms

# Deep search (IDF-ranked, dual-path retrieval)
curl localhost:8000/api/domains/{id}/deep-search?q=query+terms

# List beliefs
curl localhost:8000/api/domains/{id}/beliefs

# Explain a belief
curl localhost:8000/api/domains/{id}/beliefs/{node_id}/explain

# What-if analysis
curl localhost:8000/api/domains/{id}/beliefs/{node_id}/what-if?action=retract

# Browse data
curl localhost:8000/api/domains/{id}/sources
curl localhost:8000/api/domains/{id}/entries
curl localhost:8000/api/domains/{id}/topics

Related Projects

Reasons Forge

CLI pipeline for building domain knowledge bases from documentation.

Reasons App

Desktop menu bar app with a local MCP server for on-device knowledge bases.