HUMAN THEORY APPS

# 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:

1. 000_INIT — Session anchor is initialized (or resumed). Identity tokens are minted if needed.
2. 111_SENSE — For search/fetch tools, reality sensing kicks in. Brave Search or URL fetching gathers raw evidence.
3. 222_REALITY — Evidence is processed, deduplicated, and optionally ingested into the Qdrant vector store.
4. 333_MIND — Constitutional audit rules are checked against the evidence and query.
5. 444_ROUTER — The governance kernel routes the query through all 13 constitutional floors.
6. 555_MEMORY — Relevant session memory is retrieved and stored.
7. 666_HEART — Ethical evaluation assesses harm, fairness, and compassion.
8. 777_CRITIQUE — The self-critique engine challenges assumptions.
9. 888_JUDGE — Final judgment is rendered: SEAL, HOLD, or VOID.
10. 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
        }
      }
    }