telos-mcp

Model Context Protocol server for TELOS AI Labs governance.

Exposes TELOS governance primitives -- action scoring, unsigned integrity-hash receipt verification, Purpose Anchor inspection, audit-chain queries, and CCRS counterfactual replay -- as MCP tools, resources, and prompts. Any MCP-compatible client (Claude Desktop, Claude Code, Cursor, Cline, etc.) can call them as native tools.

v0.1 status. This release ships the protocol surface with stubbed engine calls so clients can exercise every tool, resource, and prompt end-to-end without an installed engine. Scores are synthetic and receipts are unsigned integrity-hash receipts (signature: null, signing_status: "unsigned_integrity_hash"): a key-free SHA-256 over the receipt payload, not a digital signature. v0.2 wires the live telos-gov engine behind the same receipt shape, and a real signature fills the existing signature field then, with no schema break.

---

What this server exposes

Tools (LLM-callable)

Tool	Purpose
telos_score(action_name, action_params, agent_id)	Score a proposed action against the active Purpose Anchor. Returns verdict (EXECUTE / CLARIFY / ESCALATE) plus per-dimension scores across purpose, scope, boundary, tool, chain, plus an unsigned integrity-hash receipt envelope.
telos_verify(receipt_json)	Verify an unsigned integrity-hash receipt offline (key-free; not a signature check). Returns {match, recomputed_integrity_hash, signing_status, reason, ...}.
telos_get_pa(agent_id)	Return the active Purpose Anchor: purpose, hard boundaries, declared scope, allowed tools, centroid dimensions.
telos_audit(start_iso, end_iso)	Return audit-chain entries within a time window (capped at 100).
telos_replay(receipt_id, alt_config_path)	Queue a CCRS counterfactual replay against an alternate config; returns a job_id.

Resources (LLM-readable)

URI template	Returns
telos://wiki/{path}	A TELOS governance wiki page by relative path.
telos://centroids/{dimension}	Compiled centroid metadata for one of purpose, scope, boundary, tool, chain.
telos://audit/{date}	The audit-chain segment for a given YYYY-MM-DD (UTC).

Prompts (user-invokable templates)

Prompt	Purpose
governance_review(action)	Have the model review a proposed action for governance compliance.
audit_walkthrough(start_date, end_date)	Walk through the audit chain in a date window.

---

Install

pip install telos-mcp

The live engine (telos-gov) lands in v0.2, after the clean-facade republish. v0.1 ships no installable engine extra; the stub is the only supported engine. (telos-mcp[engine] returns in v0.2 pinned to the republished clean facade.)

The package installs a telos-mcp console script that starts the server over stdio. You can also invoke it via python -m telos_mcp.server.

Requires Python 3.10+.

---

Client configuration

Each client below assumes telos-mcp is installed in a Python environment on PATH. If you prefer not to install globally, use uvx telos-mcp or substitute the absolute path to the telos-mcp script in the snippets.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows). Add the telos-governance entry under mcpServers:

{
  "mcpServers": {
    "telos-governance": {
      "command": "telos-mcp",
      "args": [],
      "env": {
        "TELOS_AGENT_ID": "claude-desktop-default"
      }
    }
  }
}

Restart Claude Desktop. The five telos_* tools should appear in the MCP tool tray.

Claude Code

Use the claude mcp add CLI:

claude mcp add telos-governance -- telos-mcp

Or edit ~/.config/claude-code/mcp_servers.json directly:

{
  "telos-governance": {
    "command": "telos-mcp",
    "args": []
  }
}

Cursor

Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project):

{
  "mcpServers": {
    "telos-governance": {
      "command": "telos-mcp",
      "args": [],
      "env": {
        "TELOS_AGENT_ID": "cursor-default"
      }
    }
  }
}

Cline (VS Code extension)

Open Cline -> MCP Servers -> Edit Configuration. Add:

{
  "mcpServers": {
    "telos-governance": {
      "command": "telos-mcp",
      "args": [],
      "transportType": "stdio"
    }
  }
}

Verifying the install

From any client, ask:

Use the telos_get_pa tool with agent_id="test" and show the Purpose Anchor.

You should see a stub PA back containing "stub": true and the five canonical centroid dimensions.

---

Development

git clone https://github.com/TELOS-Labs-AI/telos-mcp
cd telos-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Run the server over stdio (what MCP clients spawn):
python -m telos_mcp.server

# Non-interactive startup smoke check (closes stdin; exits successfully):
python -m telos_mcp.server < /dev/null

# Run protocol and governance contract tests:
python -m pytest tests

# Install and test the declared minimum MCP SDK in a disposable environment:
python tools/check_mcp_floor.py

The stdio server waits for an MCP client when stdin is open. The startup smoke check above tests clean startup and EOF shutdown; the test suite also performs a real client initialization handshake. The development extra supplies the test and lint tools; interactive Inspector tooling is not included.

---

Roadmap

• v0.1 (this release) -- protocol surface complete, engine stubbed, registry-submission-ready manifest.
• v0.2 -- swap stubs for live telos-gov calls (after the clean-facade republish). Receipts gain a real signature after the signing ceremony, filling the existing signature field with no schema break. telos-gov becomes a hard dependency.
• v0.3 -- streaming audit subscriptions, per-tenant PA selection via TELOS_TENANT env, optional HTTP transport.

---

License

Apache-2.0. See LICENSE.

Links

• TELOS AI Labs: https://telos-labs.ai
• Source: https://github.com/TELOS-Labs-AI/telos-mcp
• Issues: https://github.com/TELOS-Labs-AI/telos-mcp/issues