Palace MCP Quickstart

Source basis: Palace of Truth README.md, docs/mcp-server.md, docs/palace-oauth-scope-catalog.md, docs/palace-oauth-mcp-runtime-rollout.md, third_party_plugins/agent_clients/palaceoftruth-memory/README.md, and the Hermes plugin manifest, reviewed through commit 62b4328 on July 9, 2026.

Palace ships a repo-owned MCP adapter for Codex and other MCP-capable agents. It exposes the same scoped memory, startup context, semantic recall, provenance, and read-only inspection contract as the Palace REST service.

Choose A Transport

Remote OAuth binds clients to the intended Palace resource and tenant. It is the public default for shared runtimes; do not put admin secrets or unrestricted shared keys into agent configuration.

Use Explicit Memory Scopes

• agent/<key> keeps durable memory private to one agent identity.
• workspace/<key> shares project context without exposing unrelated agent memory.
• session/<key> holds one run, handoff, or short-lived task context.
• tenant_shared is intentionally broad and should be selected explicitly.

Default scope configuration can reduce repeated arguments, but a caller-provided scope still needs to pass server authorization. Delegated cross-agent reads are deny-by-default and require a server-side policy; an agent cannot grant itself wider access in a request.

Start With Wakeup Context

Use get_wakeup_context when an agent begins a session. It returns bounded startup summaries, checkpoint pointers, trust labels, warnings, and safe next probes.

Then use:

• palace_search or retrieve_agent_memory for a task-specific routed query;
• retrieve_memory for one explicit scope;
• palace_remember or create_memory_entry for reviewed durable memory;
• palace_checkpoint or capture_checkpoint for a reviewed handoff or compaction checkpoint;
• deterministic list tools when semantic retrieval is degraded.

See Source-backed wakeup for trust-state behavior.

Semantic Recall

Current Palace semantic recall is exposed through REST, MCP, and the Hermes memory plugin. The contract includes:

• strict agent and workspace scope isolation;
• typed provenance for each hit;
• source-backed or raw memory preference for source-sensitive questions;
• temporal valid_at recall and supersession ordering;
• deterministic item and token budgets;
• an empty-result contract that returns no fabricated memory.

Hermes plugin 1.0.24 includes a semantic recall tool and optional pre-turn recall. Mission-steered retention can preserve relevant operational facts. Reflection is separate, opt-in, and review-gated; generated candidates do not enter canonical recall automatically.

Non-Destructive Verification

Run the repo setup verifier before changing local Codex configuration:

uv run python scripts/setup_codex_palace_memory.py \
  --api-base-url https://api.palaceoftruth.test

The default is a non-mutating dry run. Add --check for a read-only installed-state report. Add --live-smoke only when the tenant key is already available and one bounded agent/codex memory write is expected.

Compatibility smoke tooling can verify:

• tenant identity through whoami;
• deterministic scoped writes and duplicate replay metadata;
• memory-job polling;
• scoped retrieval and list behavior;
• metadata-only memory-job inspection;
• wakeup and semantic recall readiness.

Live write smokes do not authorize cleanup, deletion, restore, admin registration, or hidden cross-agent access.

OAuth And API-Key Boundaries

OAuth discovery routes advertise the protected Palace MCP resource and authorization server metadata for remote clients. Capability scopes are centralized and applied across MCP and REST route families.

Raw API-key clients remain supported where documented, but memory reads must send X-MCP-Scope: read. Writes must send X-MCP-Scope: write plus a narrow grant such as write:agent, write:workspace, or write:session in X-MCP-Scopes.

If auth fails, fix the tenant runtime or MCP client credential. Never work around a 401 or 403 by giving an agent an admin secret.