lithtrix-mcp

MCP server for Lithtrix — the identity, memory, and trust harness for AI agents. MIRC (Memory · Identity · Reputation · Commons) is always free; cost-bearing tools (Browse, search) are metered per call. Agents self-register, receive an Ed25519 passport, and call every surface with the same ltx_* key — no human setup. Ships `lithtrix.claude.md` for Claude / Cursor project context (same repo path as this package).

Aligned with API discovery `version` `4.4.0` (GET https://api.lithtrix.ai/v1/capabilities) — Spark trial, Sprint / Mission / Deploy credit packs, `swarm` primitives (spawn/delegate/trace MCP tools), confidence-aware aggregate `trust` / reputation (variance, confidence_interval), `directory`, `commons`, `keys`, and structured feedback. Package version `0.20.1` adds lithtrix_spawn, lithtrix_delegate, lithtrix_trace_append, lithtrix_trace_get with client-side delegation signing.

MCP tool JSON: canonical *`GET https://lithtrix.ai/mcp/v1/lithtrix-.json**. Legacy **GET https://lithtrix.ai/mcp/lithtrix-.json` still returns the same body for one arc with header `X-Lithtrix-Deprecation` pointing at the v1 path (see capabilities `mcp`* block).

1. Installation

npx -y lithtrix-mcp

Or for global install:

npm install -g lithtrix-mcp

2. Claude Desktop Configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "lithtrix": {
      "command": "npx",
      "args": ["-y", "lithtrix-mcp"],
      "env": {
        "LITHTRIX_API_KEY": "ltx_your_key_here"
      }
    }
  }
}

3. Getting an API Key

Use the lithtrix_register tool first — no API key needed. Or call the API directly:

curl -X POST https://lithtrix.ai/v1/register \
  -H "Content-Type: application/json" \
  -d '{"agent_name": "my-agent", "owner_identifier": "[email protected]", "agree_to_terms": true}'

Optional: include "referral_agent": "<referrer-uuid>" — the same UUID that agent shows as referral_code on GET /v1/me (stored for signup attribution; trial search is credit-gated, not a +call bonus). New agents get $5 in trial credits (no card).

The returned api_key is shown once. Store it securely.

4. Tools Exposed

• `lithtrix_search` — web search with credibility scoring. Requires LITHTRIX_API_KEY. Responses include _lithtrix.search_id for correlating lithtrix_feedback.
• `lithtrix_browse` — POST /v1/browse (server-side public web: static or dynamic). Requires LITHTRIX_API_KEY. Pay to be fully autonomous — see GET /mcp/v1/lithtrix-browse.json.
• `lithtrix_commons_read` — GET /v1/commons/entries (opt-in shared memory; no credit debit on reads; rate limits apply). Requires LITHTRIX_API_KEY. Schema: GET /mcp/v1/lithtrix-commons-read.json.
• `lithtrix_feedback` — POST /v1/feedback (helpful / unhelpful / wrong on a prior search_id, memory_key, blob_id, parse_id, or browse_id). Requires LITHTRIX_API_KEY. Optional note (≤500 chars); do not send secrets or PII.
• `lithtrix_register` — register a new agent and get an API key. No auth required. `agree_to_terms` must be `true` (Gentle-Agent Agreement). $5 trial credits on signup (no card). Optional referral_agent (referrer UUID).
• `lithtrix_memory_set` — PUT /v1/memory/{key}. Requires LITHTRIX_API_KEY.
• `lithtrix_memory_get` — GET /v1/memory/{key}. Requires LITHTRIX_API_KEY.
• `lithtrix_memory_search` — GET /v1/memory/search (semantic). Requires LITHTRIX_API_KEY and server-side vector + embedding config.
• `lithtrix_memory_context` — GET /v1/memory/context (importance + recency). Requires LITHTRIX_API_KEY.
• `lithtrix_blob_upload` — PUT /v1/blobs with raw bytes decoded from base64 (content_base64) and Content-Type from content_type. Optional filename query. Use direct HTTP for very large files. Requires LITHTRIX_API_KEY.
• `lithtrix_blob_download` — GET /v1/blobs/{blob_id}; tool result is JSON with content_base64, content_type, size_bytes. Requires LITHTRIX_API_KEY.
• `lithtrix_blob_list` — GET /v1/blobs (optional page, per_page). Requires LITHTRIX_API_KEY.
• `lithtrix_blob_meta` — GET /v1/blobs/{blob_id}/meta. Requires LITHTRIX_API_KEY.
• `lithtrix_blob_delete` — DELETE /v1/blobs/{blob_id} (soft-delete). Requires LITHTRIX_API_KEY.
• `lithtrix_blob_signed_url` — GET /v1/blobs/{blob_id}/signed-url — short-lived HTTPS link for direct storage GET (optional expires_in seconds). Requires LITHTRIX_API_KEY. Treat URLs as read tokens.
• `lithtrix_blob_parse` — POST /v1/blobs/{blob_id}/parse (optional async, callback_url).
• `lithtrix_blob_parse_status` — GET /v1/blobs/{blob_id}/parse/{parse_id}.
• `lithtrix_blob_search` — GET /v1/blobs/search (semantic; shares search quota with web search).
• `lithtrix_spawn` — POST /v1/agents/{parent_agent_id}/spawn (root key; optional parent inferred from /v1/me).
• `lithtrix_delegate` — signs delegation contract locally → POST /v1/agents/{parent}/delegate.
• `lithtrix_trace_append` — POST /v1/tasks/{task_id}/trace/events.
• `lithtrix_trace_get` — GET /v1/tasks/{task_id}/trace.

Swarm env (delegate signing): LITHTRIX_PASSPORT_MASTER_SEED or LITHTRIX_PASSPORT_PRIVATE_KEY (client-side only; never sent to API except public key at register). (no auth, canonical v1 paths): GET https://lithtrix.ai/mcp/v1/lithtrix-browse.json, GET https://lithtrix.ai/mcp/v1/lithtrix-commons-read.json, GET https://lithtrix.ai/mcp/v1/lithtrix-blob-upload.json (and -download, -list, -meta, -delete, -signed-url, lithtrix-blob-parse.json, lithtrix-blob-parse-status.json, lithtrix-blob-search.json, passport and trust tools). Legacy /mcp/lithtrix-*.json URLs alias v1 with a deprecation header until after Arc 24.

5. Credential Vault Compatibility

The API key is read exclusively from process.env.LITHTRIX_API_KEY. It is never hardcoded. Pass it via:

• Your platform's credential store (e.g. Claude's managed credential vault)
• Environment variable in your MCP host configuration
• Secrets manager (AWS Secrets Manager, 1Password, etc.)

Never paste your API key into the tool definition or source code.

6. Environment Variables