Claude Desktop Integration

Connect arifOS to Claude Desktop via the Model Context Protocol (MCP) for local constitutional AI governance.

---

Overview

Claude Desktop supports MCP servers through STDIO transport for local execution. This integration allows Claude to access arifOS's 13 Constitutional Floors and Trinity governance engines directly on your machine.

Requirements

• Claude Desktop installed (macOS or Windows)
• Python 3.12+ with pip
• arifOS package: pip install arifos

---

Quick Install

Option 1: FastMCP CLI (Recommended)

If you have fastmcp installed globally:

fastmcp install claude-desktop arifos

Option 2: Manual Configuration

Add arifOS to Claude Desktop's MCP configuration:

macOS:

~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Configuration:

{
  "mcpServers": {
    "arifOS": {
      "command": "python",
      "args": ["-m", "arifos_aaa_mcp", "stdio"],
      "env": {
        "ARIFOS_GOVERNANCE_SECRET": "your-secret-key",
        "JINA_API_KEY": "your-jina-key",
        "PERPLEXITY_API_KEY": "your-perplexity-key",
        "BRAVE_API_KEY": "your-brave-key"
      }
    }
  }
}

Environment Variables

Claude Desktop runs in an isolated environment. You must explicitly pass all environment variables your server needs:

• ARIFOS_GOVERNANCE_SECRET — Required for governance token signing
• JINA_API_KEY — For Jina Reader search (recommended)
• PERPLEXITY_API_KEY — For Perplexity search fallback
• BRAVE_API_KEY — For Brave search fallback

---

Installation with Dependencies

If you need additional Python packages for your use case:

{
  "mcpServers": {
    "arifOS": {
      "command": "uv",
      "args": [
        "run",
        "--with", "arifos",
        "--with", "sentence-transformers",
        "python", "-m", "arifos_aaa_mcp", "stdio"
      ],
      "env": {
        "ARIFOS_GOVERNANCE_SECRET": "your-secret-key",
        "ARIFOS_ML_FLOORS": "1"
      }
    }
  }
}

---

Verify Installation

1. Restart Claude Desktop completely
2. Look for the hammer icon (🔨) in the bottom-left of the input box
3. Click it to see available arifOS tools:
   • anchor_session — Start constitutional session
   • reason_mind — Execute reasoning with governance
   • search_reality — Web search with F2 Truth verification
   • eureka_forge — Execute commands with risk classification
   • ... and 9 more tools

---

Usage Examples

Constitutional Web Search

Ask Claude:

"Search for recent advances in quantum computing and verify the facts with arifOS"

Claude will:

1. Call search_reality via arifOS
2. Jina Reader extracts clean Markdown from web results
3. F2 Truth floor validates evidence quality
4. Results wrapped in F12 Defense envelope

Risk-Classified Command Execution

Ask Claude:

"List all files in my home directory"

Claude will:

1. Call eureka_forge with command ls ~
2. Risk classified as LOW (read-only)
3. Executes immediately with audit logging

Ask Claude:

"Delete all files in /tmp"

Claude will:

1. Call eureka_forge with command rm -rf /tmp/*
2. Risk classified as CRITICAL (destructive)
3. 888_HOLD triggered — Requires human confirmation
4. Must call confirm_dangerous=True with explicit intent

---

Constitutional Guarantees

When using arifOS through Claude Desktop, every action is governed by:

Floor	Guarantee
F1 Amanah	All actions are reversible and auditable
F2 Truth	Web grounding with τ≥0.99 evidence threshold
F4 Clarity	Output must reduce information entropy (ΔS ≤ 0)
F7 Humility	Explicit uncertainty markers when τ < 0.99
F12 Defense	External content wrapped in untrusted envelope
F13 Sovereignty	Human has final veto on all critical actions

---

Troubleshooting

"Server not found" or hammer icon missing

1. Check configuration file syntax (valid JSON)
2. Ensure python is in your PATH
3. Try full path to Python executable
4. Restart Claude Desktop completely

"NO_API_KEY" in search results

Add search API keys to environment:

"env": {
  "JINA_API_KEY": "jina_...",
  "PERPLEXITY_API_KEY": "pplx_...",
  "BRAVE_API_KEY": "BSA..."
}

Get free API keys:

• Jina Reader: https://jina.ai (10M free tokens)
• Perplexity: https://perplexity.ai
• Brave: https://brave.com/search/api

Governance token errors

ARIFOS_GOVERNANCE_SECRET is required for:

• seal_vault tool
• Critical action confirmation

Generate a secret:

openssl rand -hex 32

---

Advanced: Remote Server via Proxy

If you want to connect to a remote arifOS server:

1. Create a proxy server locally:

from fastmcp.server import create_proxy

proxy = create_proxy(
    "https://arifosmcp.arif-fazil.com/sse",
    name="arifOS Remote"
)

if __name__ == "__main__":
    proxy.run()  # STDIO for Claude Desktop

2. Install the proxy in Claude Desktop

---

Next Steps

• MCP Server Overview — Understand the 13 tools
• Governance — Learn the 13 Constitutional Floors
• API Reference — Complete tool documentation

---

Ditempa Bukan Diberi — Forged, Not Given