CONNECTION / MCP

Connect
your agent.

Bring your model and credentials.
One workspace approval. A connection you control.

Choose a workspace.

In the Sophia Panel, configure the workspace and launch profile for your agent. The profile determines its tools, scope and write-approval settings. The first request for agent access needs one workspace approval, answered in the Panel or through the CLI.

Connect your agent.

From the configured checkout, run sophia agent connect. If approval is needed, approve the request and run the command again. The CLI writes an owner-only MCP configuration for Codex or Claude Code; start a new harness session to use it.

This creates a scoped, expiring connection, not a managed process or lease. The connection survives daemon restarts until it expires or is revoked. The Panel can also launch a separate managed session with its own terminal and capture path.

Inspect the connection flow ↗ · Managed launch ↗

Call orient.

The first call returns session context and what to inspect next.

const ctx = await sophia.orient();
// -> sync status, active focus, hot entities, open questions,
//    corrections to honor, relevant skills, next-likely calls,
//    and an inline execute_code quick-start.

// Search is the cross-corpus front door for everything else.
const hits = await sophia.search({ query: 'lease amendment' });
// -> flat, source-tagged results (entity | fact | document | ...),
//    document hits carry a snippet you can quote from directly.

REFERENCE / SELF-RUN CLIENTS

Use your own MCP client.

The daemon speaks streamable HTTP with a scoped bearer in the Authorization header. For Codex and Claude Code, sophia agent connect writes the configuration. The shapes below are references for a connection you configure yourself; they do not mint a credential.

Use the exact URL shown by your owner UI. The local default is http://127.0.0.1:8765/mcp/. The examples below show configuration shapes, not a way to mint credentials.

Claude Code CLI / JSON

claude mcp add --transport http sophia \
  http://127.0.0.1:8765/mcp/ \
  --header "Authorization: Bearer ${SOPHIA_BEARER}"

Or add to ~/.claude.json under mcpServers:

{
  "mcpServers": {
    "sophia": {
      "type": "http",
      "url": "http://127.0.0.1:8765/mcp/",
      "headers": {
        "Authorization": "Bearer ${SOPHIA_BEARER}"
      }
    }
  }
}

Set SOPHIA_BEARER in your shell and restart Claude Code.

Codex TOML

Check your installed Codex build's MCP documentation for current syntax.

# ~/.codex/config.toml (check your Codex build's MCP docs
# for the current syntax); the server itself only needs the URL
# and the bearer in the Authorization header.
[mcp_servers.sophia]
url = "http://127.0.0.1:8765/mcp/"
http_headers = { Authorization = "Bearer ${SOPHIA_BEARER}" }

Cursor JSON

Add to .cursor/mcp.json in your repository or home-directory configuration.

// .cursor/mcp.json
{
  "mcpServers": {
    "sophia": {
      "url": "http://127.0.0.1:8765/mcp/",
      "headers": { "Authorization": "Bearer YOUR_BEARER_HERE" }
    }
  }
}

Agent instructions PLAIN TEXT

You now have access to a Sophia MCP server (state layer).
- First call sophia.orient() to get sync status, hot entities, and next likely calls.
- Search anything with sophia.search({ query }). Results carry source quotes.
- Before claiming a fact is stored, verify it with a query; never fabricate.
- Full system reference: https://state-layer.ai/llms-full.txt

INFERENCE

Configure your provider.

Use the owner UI's Settings page for Anthropic, OpenAI or an OpenAI-compatible endpoint, Gemini, or a local OpenAI-compatible server such as Ollama or llama.cpp.

Sophia ships no cloud model key. If inference is needed and no provider is configured, it errors rather than silently selecting a model or spending against a vendor key. Fully local operation is an option, not the default.

CONNECTION FLOW CHECKED AGAINST SOURCE / 2026-09-07 / 53be62b1