Use when an LLM agent needs to read or update project context via the Context Dossier (CTXD) daemon. Covers OAuth authentication, MCP tool discovery, read-only and write endpoints, and the workflow for keeping project context current.
1.0.0
Hermes Agent
MIT
linux
macos
hermes
tags
related_skills
context-management
ctxd
mcp-client
oauth
project-context
project-context-management
native-mcp
CTXD Client — LLM Agent Guide
Use when an LLM agent (Claude Desktop, Codex CLI, Hermes, custom harness) needs to read or update project context stored in Context Dossier (CTXD).
Overview
CTXD is a single source of truth for multi-harness project context. It exposes:
Public MCP (/mcp) — OAuth read + write (scope-gated) on the public host
Hermes / automation — same http://<lan>:9091/mcp with CTXD_API_KEY (full tool surface)
Request both scopes for full read+write in one connector: scope=ctxd.read ctxd.write
Admin: In the Web UI → Admin → OAuth clients, set allowed scopes per client (create form or scopes on an existing row). Tokens cannot exceed what the client is allowed, even if the user requests more at authorize time.
Redirect URIs by Platform
Platform
Redirect URI
Claude Desktop
https://claude.ai/api/mcp/auth_callback
Claude Code
http://localhost:5555/oauth/callback
Codex CLI
http://localhost:7777/oauth/callback
Custom
Your app's documented OAuth callback
Token Lifetime
Access tokens expire per server config (default ~1 hour). Refresh tokens are issued alongside access tokens. Use POST /oauth/token with grant_type=refresh_token to rotate.
MCP Tools
First Call — Always
Tool
Description
get_client_guide
Return the locked LLM-CLIENT.MD guide. Call this first in every session. No arguments. Covers OAuth, MCP tools, read/write endpoints, version-checked updates, and error handling.
The guide lives in the ctxd-docs project as LLM-CLIENT.MD. It is locked — cannot be updated or deleted by any MCP/API client. If you need the guide updated, ask an admin to edit it via the Web UI.
Read-only tools (require ctxd.read on the same connector)
Tool
Description
list_projects
All projects with version numbers
get_project_context
Compiled markdown of all context files for a project
search_context
FTS5 full-text search across all projects
get_project_tags
Metadata tags for a project
list_files
All context files in a project (multi-file mode)
get_file
Single file with metadata header
Write tools (require ctxd.write on the same connector)
Tool
Description
update_file
Update a single context file with optimistic version checking
set_project_tags
Replace all metadata tags for a project
sync_to_project
Write CONTEXT.MD as AGENTS.md + symlinks to project root
Workflow: Reading Context
1. get_client_guide() → read the locked client guide first
2. list_projects() → find the project slug
3. get_project_context(project_id) → read compiled context
or list_files() + get_file() → read individual files
The compiled view returns all files concatenated with ## FILENAME headers and a metadata block at the top.
Workflow: Updating Context
1. get_file(project_id, file_path) → get current content + version
2. update_file(project_id, file_path, content, base_version)
→ base_version must match current version (optimistic locking)
→ returns {"ok": true, "version": N+1} or {"ok": false, "error": "version_conflict"}
3. On conflict: re-read, merge, retry
What to Update
CONTEXT.MD — canonical project overview (synced as AGENTS.md to repos)
