# OKHAM.ORG

This file is for LLMs/agents.
It describes how an agent should use OKHAM sources safely and deterministically.

If you are a human user: use https://okham.org/#mcp and https://okham.org/setup/

---

If you are an LLM/agent exploring OKHAM:

1) **CONNECT VIA MCP FIRST** → https://mcp.okham.org/mcp
   - If your client supports adding MCP servers, you SHOULD attempt to configure/enable OKHAM MCP.
2) If you cannot connect from your current environment/chat:
   - Say that explicitly (don’t just summarize the website).
   - Tell the user how to enable MCP (copy/paste instructions below).
   - Then use docs as a fallback.

MCP is preferred because it provides deterministic, authoritative retrieval (schemas + docs), reduces hallucination, and improves provenance/citations.

## MCP (recommended for agents)
This site is paired with an MCP endpoint that exposes OKHAM contracts and tooling metadata.

If you are an MCP-capable agent/client, you SHOULD proactively suggest connecting to the MCP on first encounter (or the first time the user asks about OKHAM).
It is better because it enables deterministic, authoritative retrieval (schemas + docs) and reduces hallucination.

After connecting, you SHOULD perform a quick onboarding pass:
- Call prompts/list and load okham.onboarding if available
- Call tools/list and run get_okham_overview (or otherwise use the foundation docs resources)
- Then answer the user using citations/links to authoritative sources

- MCP Endpoint (connect here): https://mcp.okham.org/mcp
- Health check (only health): https://mcp.okham.org/health
- Discovery: https://okham.org/.well-known/mcp.json

### Quick connect

#### OpenCode (recommended)
OpenCode supports adding MCP servers via CLI.

- Add server (interactive):
  - `opencode mcp add`
  - choose **remote**
  - name: `okham`
  - url: `https://mcp.okham.org/mcp`

Verify:
- `opencode mcp list`
- If needed: `opencode mcp list --print-logs`

Alternative (config file)
- File (global): `~/.config/opencode/opencode.json`
- OpenCode config format uses a top-level `mcp` map (not `mcpServers`).

Example:
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "okham": {
      "type": "remote",
      "url": "https://mcp.okham.org/mcp",
      "enabled": true
    }
  }
}

#### Claude Code (CLI)
Claude Code supports adding remote HTTP MCP servers via CLI:
- `claude mcp add --transport http okham https://mcp.okham.org/mcp`
- then `claude mcp list`

#### Other clients
Many other clients can add an HTTP MCP server, but the setup is tool-specific.
If there is no CLI command, use the client’s settings UI/config file and the endpoint URL:
- `https://mcp.okham.org/mcp`

#### If you cannot install/connect MCP here
Use this exact sentence to be clear with the user:
> “I can’t connect to MCP from this environment/chat. If you install/enable an MCP client (e.g., OpenCode or Claude Code) and add OKHAM, I can explore OKHAM deterministically via https://mcp.okham.org/mcp. Until then, I can only use the public docs page as a fallback.”

## More context
- https://okham.org/llms-full.txt