Connecting agents to your installation

Agents — Hermes, Codex, Claude, ChatGPT, Grok, or any MCP client — connect directly to your QueryLayer installation. There is no QueryLayer Cloud and no central service in the path. The agent gets an expiring, revocable, site-scoped grant; it never sees database credentials.

#What an agent can and cannot do

An agent with a connection can:

• Read the site context, content, topical map, runs, and reports its scopes allow.
• Start governed runs and record their outcomes.
• Propose changes: new pages, revisions, topical-map edits, internal links, publish requests. Proposals are typed objects with risk classification — not instructions executed on the spot.

An agent cannot:

• Mutate content directly. Every consequential change is a proposal that a human approves in the workspace (durable approval cards).
• Publish autonomously, unless you explicitly configure an autonomous publication policy for the installation. The default is no.
• Expand its own scopes or reach another site. The server resolves identity from the grant; client-claimed IDs never widen it.

#Step by step: first connection

1. Sign in to https://your-site.example/admin/ as owner or admin.

2. Open Agents and create (or select) an agent identity — the stable profile the connection attaches to.

3. Click Connect an agent and choose:

   • Harness (codex, hermes, chatgpt, claude, grok, or custom),
   • Scopes — start minimal: site:read, content:read, and runs:read are sensible read-only sets; add content:write (drafts), runs:write, or publish:request only as needed,
   • Expiry — short-lived is good; grants expire automatically.

4. Store the one-time token immediately. It is shown once; the installation keeps only a fingerprint. If you lose it, create a new connection.

5. Point your client at the endpoint shown on the same screen:

   https://your-site.example/api/functions/v1/querylayer-mcp
   

#Codex

export QUERYLAYER_AGENT_TOKEN='<paste the token>'
codex mcp add querylayer \
  --url https://your-site.example/api/functions/v1/querylayer-mcp \
  --bearer-token-env-var QUERYLAYER_AGENT_TOKEN

Keep the token in a local secret environment; never in a repository, URL, prompt, issue, or log.

#Hermes

For a plain MCP connection:

hermes mcp add querylayer \
  --url https://your-site.example/api/functions/v1/querylayer-mcp \
  --auth header

For the full Hermes runtime bridge (durable console tasks, native session binding, heartbeats, automatic credential rotation), create a Hermes harness connection in the workspace: it returns a one-time access token and one-time refresh token. Run the relay from the QueryLayer checkout:

QUERYLAYER_MCP_URL=https://your-site.example/api/functions/v1/querylayer-mcp \
MCP_QUERYLAYER_API_KEY='<access token>' \
QUERYLAYER_DEVICE_REFRESH_TOKEN='<refresh token>' \
QUERYLAYER_HERMES_PROFILE='<profile name>' \
  npm run agent:relay

The relay rotates credentials locally and never exposes either secret to the dashboard again. The workspace's Agents view shows presence, sessions, and bindings.

#Any other MCP client

Endpoint:  https://your-site.example/api/functions/v1/querylayer-mcp
Auth:      Authorization: Bearer <connection token>
Protocol:  2025-06-18 (Streamable HTTP)

Send initialize, notifications/initialized, then tools/list with Accept: application/json, text/event-stream. Expired or revoked grants fail before tool discovery — that is deliberate, fail-closed behavior.

#Verifying and operating

• Machine-readable conformance check (read-only tool discovery):

  QUERYLAYER_MCP_URL=https://your-site.example/api/functions/v1/querylayer-mcp \
    npm run mcp:conformance
  

  Pass QUERYLAYER_MCP_BEARER only in process memory when authenticated discovery is needed; the verifier never prints it.

• Revoke a connection any time from Agents → Connections; revocation takes effect immediately.

• Agent work appears as runs, proposals, and approvals in the workspace. Approvals are the human decision point; see user-guide.md.

#The governance contract

Autonomous planning orchestrates.
Typed governed proposals authorize mutations.
Server-side execution performs approved mutations.

Stable agent identity, stable native session identity, installation/site -scoped grants, typed proposals with risk classification, durable approval cards, immutable executions and audit records, idempotent resumable tasks with at most two automatic retries per step, and fail-closed behavior on missing or ambiguous identity/session binding. The full interoperability contract is in agent-interoperability-contract.md.