# arifOS MCP — Developer Reference for LLMs
# Version: v2026.05.22-GDK
# Status: CURRENT TRANSPORTED CONTEXT

## Summary

arifOS MCP is the governed action gateway for the arifOS Federation. It exposes 13 canonical MCP tools and adds governance around discovery, tool choice, permission, risk, reversibility, human approval, and audit.

Use this file as transported context only. The current human SOT is:

```text
https://arifos.arif-fazil.com/docs/MCP_SOURCE_OF_TRUTH.md
```

The current machine-readable discovery index is:

```text
https://arifos.arif-fazil.com/mcp-discovery-index.json
```

## Endpoints

- Public MCP gateway: `https://mcp.arif-fazil.com/mcp`
- arifOS service MCP endpoint: `https://arifos.arif-fazil.com/mcp`
- Health: `https://arifos.arif-fazil.com/health`
- Tools registry: `https://arifos.arif-fazil.com/tools`
- Server manifest: `https://arifos.arif-fazil.com/.well-known/mcp/server.json`
- Federation probe: `https://arifos.arif-fazil.com/api/federation-probe`

`https://arifosmcp.arif-fazil.com/mcp` is legacy. Prefer the public gateway or service endpoint above.

## MCP Client Config

```json
{
  "mcpServers": {
    "arifos": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.arif-fazil.com/mcp"],
      "transport": "streamable-http"
    }
  }
}
```

## Direct JSON-RPC

```bash
curl -fsS -X POST https://mcp.arif-fazil.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":1}'
```

## Canonical arifOS Tools

| Tool | Purpose |
|---|---|
| `arif_session_init` | Session and identity binding |
| `arif_sense_observe` | Reality observation and hybrid discovery |
| `arif_evidence_fetch` | Evidence retrieval with receipts |
| `arif_mind_reason` | Reasoning, planning, verification |
| `arif_heart_critique` | Risk, empathy, red-team critique |
| `arif_kernel_route` | Intent routing and topology |
| `arif_reply_compose` | Governed response composition |
| `arif_memory_recall` | Governed memory recall/store/list |
| `arif_gateway_connect` | Federation/A2A gateway |
| `arif_judge_deliberate` | Constitutional deliberation |
| `arif_vault_seal` | VAULT999 audit/seal surface |
| `arif_forge_execute` | Bounded execution/forge action |
| `arif_ops_measure` | Health, cost, telemetry |

## Governed Discovery Kernel

Before high-consequence action, orient with:

```text
arif_sense_observe(mode="compass")
```

`compass` is the GDK orientation loop. It uses `hybrid_discovery` as the read-only evidence engine.

The Capability Manifest Loop:

```text
Intent -> discovery -> capability manifest -> relevance/risk/permission check
  -> narrowed action -> human judgment if needed -> execute or stop
  -> audit -> discovery map update
```

Required manifest fields:

- `can_do`
- `cannot_do`
- `required_inputs`
- `outputs`
- `permissions`
- `risks`
- `reversibility`
- `audit`
- `human_approval`

## Federation Runtime Counts

Verified 2026-05-22:

- arifOS: 13 MCP tools, healthy.
- GEOX: 22 MCP tools, healthy.
- WEALTH: 17 MCP tools, healthy.
- WELL: 15 MCP tools, healthy, REFLECT_ONLY.
- Wiki: static knowledge surface, 0 MCP tools.

## Boundary Rules

- Available does not mean allowed.
- Relevant does not mean true.
- Possible does not mean safe.
- Automation does not replace judgment.
- Access does not create authority.

MCP transports capability. arifOS governs capability. APEX may deliberate. Arif remains final sovereign authority.
