Getting Started

Install arifOS MCP, configure your environment, and make your first constitutional governance query in minutes.

Prerequisites

Python ≥ 3.12 — required for the FastMCP runtime
FastMCP ≥ 3.1.0 — the MCP server framework (installed automatically)
Brave Search API key — for reality_compass search capability
Qdrant (optional) — for reality_atlas vector storage

Installation

Via pip

bash

pip install arifosmcp

Via pip (with extras)

bash

# Install with Qdrant support for reality_atlas
pip install arifosmcp[qdrant]

# Install with all optional dependencies
pip install arifosmcp[all]

Via Docker

bash

# Pull the official image
docker pull ghcr.io/ariffazil/arifosmcp:latest

# Run with environment variables
docker run -d \
  --name arifosmcp \
  -p 8080:8080 \
  -e BRAVE_API_KEY=your_key_here \
  -e ARIFOS_LOG_LEVEL=INFO \
  ghcr.io/ariffazil/arifosmcp:latest

Quick Start

Running the Server

arifOS MCP supports three transport modes:

STDIO (for Claude Desktop, Cursor, etc.)

bash

# Default STDIO transport
python -m arifosmcp

# Or use the CLI
arifosmcp serve

HTTP (Streamable HTTP transport)

bash

# Start HTTP server on port 8080
arifosmcp serve --transport http --port 8080

# Or with uvicorn directly
uvicorn arifosmcp.server:app --host 0.0.0.0 --port 8080

Docker

bash

docker run -p 8080:8080 \
  -e BRAVE_API_KEY=your_key \
  ghcr.io/ariffazil/arifosmcp:latest

Your First Query

Python

python

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    server = StdioServerParameters(
        command="python",
        args=["-m", "arifosmcp"]
    )
    async with stdio_client(server) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # Check system health
            result = await session.call_tool("check_vital", {})
            print(result)

            # Search with constitutional governance
            result = await session.call_tool("reality_compass", {
                "input": "quantum computing breakthroughs 2026"
            })
            print(result)

import asyncio
asyncio.run(main())

curl

bash

# Check system health
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "check_vital",
      "arguments": {}
    }
  }'

What Happens in a Request

When you call a tool through arifOS MCP, this is the flow:

000_INIT — Session anchor is initialized (or resumed). Identity tokens are minted if needed.
111_SENSE — For search/fetch tools, reality sensing kicks in. Brave Search or URL fetching gathers raw evidence.
222_REALITY — Evidence is processed, deduplicated, and optionally ingested into the Qdrant vector store.
333_MIND — Constitutional audit rules are checked against the evidence and query.
444_ROUTER — The governance kernel routes the query through all 13 constitutional floors.
555_MEMORY — Relevant session memory is retrieved and stored.
666_HEART — Ethical evaluation assesses harm, fairness, and compassion.
777_CRITIQUE — The self-critique engine challenges assumptions.
888_JUDGE — Final judgment is rendered: SEAL, HOLD, or VOID.
999_VAULT — The verdict and response are sealed into the SHA-256 Merkle chain.

Note

Not all stages run for every tool. Simple tools like check_vital skip the full metabolic pipeline. The arifOS_kernel tool is the only one that always traverses the complete 000–999 loop.

Environment Variables

Variable	Required	Default	Description
`BRAVE_API_KEY`	Yes	—	API key for Brave Search (used by reality_compass)
`QDRANT_URL`	No	`http://localhost:6333`	Qdrant vector database URL (used by reality_atlas)
`QDRANT_API_KEY`	No	—	API key for Qdrant Cloud
`ARIFOS_LOG_LEVEL`	No	`INFO`	Logging level (DEBUG, INFO, WARNING, ERROR)
`ARIFOS_VAULT_PATH`	No	`./vault`	Path to VAULT999 ledger storage
`ARIFOS_SESSION_TTL`	No	`3600`	Session time-to-live in seconds
`ARIFOS_MAX_SEARCH_RESULTS`	No	`10`	Max results from Brave Search
`ARIFOS_TRANSPORT`	No	`stdio`	Transport mode: stdio, http
`ARIFOS_PORT`	No	`8080`	HTTP server port (when transport=http)

VPS Architecture

For production deployments, the recommended VPS setup includes:

text

┌─────────────────────────────────────────┐
│              VPS / Cloud VM              │
│                                          │
│  ┌──────────┐  ┌──────────┐  ┌────────┐ │
│  │ arifOS   │  │  Qdrant  │  │ VAULT  │ │
│  │ MCP      │──│  Vector  │  │  999   │ │
│  │ Server   │  │  Store   │  │ Ledger │ │
│  └────┬─────┘  └──────────┘  └────────┘ │
│       │                                   │
│  ┌────┴─────┐                            │
│  │  Nginx   │  ← TLS termination         │
│  │  Reverse │                            │
│  │  Proxy   │                            │
│  └────┬─────┘                            │
│       │                                   │
└───────┼───────────────────────────────────┘
        │
    Internet ← MCP clients connect here

Nginx handles TLS termination and reverse proxies to the MCP server
Qdrant runs as a separate service for vector storage
VAULT999 stores the Merkle chain on persistent disk
All services are containerized with Docker Compose

3E Telemetry

Every response includes 3E telemetry data in the governance envelope:

json

{
  "telemetry": {
    "epistemic": {
      "confidence": 0.87,
      "evidence_count": 5,
      "source_diversity": 0.72
    },
    "ethical": {
      "harm_score": 0.02,
      "fairness_score": 0.95,
      "compassion_flag": false
    },
    "execution": {
      "latency_ms": 1240,
      "tokens_used": 3200,
      "budget_remaining": 0.68
    }
  }
}