Choose the task first. Connecting a harness and administering the server use different credentials.
| Task | Start here | Required access |
|---|---|---|
| Run an HTTP MCP server | Deployment | Access to the brain host and its service configuration |
| Open the admin panel or manage clients | MCP administration | The running server's separate owner bootstrap credential |
| Connect an existing agent | Hosted harness setup | Native OAuth/PKCE, or a private machine-client handoff |
| Wire Claude Code to a local brain in one command | gbrain setup claude-code |
A local GBrain installation; setup resolves the brain, writes MCP and read-context hooks, and verifies them |
| Run a local MCP pipe | Local stdio | A local GBrain installation; no HTTP admin panel is created |
| Diagnose a failed connection | Recovery table | Start with the failed stage and the authority you actually hold |
| A tool call returned an error | A tool call returned an error | None: the error says who acts |
For agents: read the MCP access skill.
If skill tools are unavailable, the instructions here and in
ADMIN.md work directly. A connected harness can also read
gbrain://capabilities for its effective permissions and administration guidance.
Owner administration is separate from MCP admin scope. An OAuth access
token, client secret, or ordinary MCP connection does not authorize dashboard
login, client creation, or client revocation. A public PKCE client has no client
secret. Ask the server-hosting harness or a separately authorized administrator
to perform owner actions.
Say to that administrator: “Open the admin panel for my running GBrain server. Use its configured endpoint and protected owner credential. Give me a fresh single-use login link without opening it yourself.”
Say to the connecting agent: “Connect this harness to my hosted GBrain. Use its native OAuth flow if available; otherwise use a private machine handoff. Follow the hosted setup guide and report configuration separately from an observed connection in this harness.”
Tool descriptions are deliberately short (the starter list is pinned at 25,000
characters by test/mcp-schema-budget.test.ts); the longer guidance for each
starter tool is in the MCP tool reference.
Client-specific details: ChatGPT, Claude Code, Claude Desktop, Codex, opencode, Perplexity, OpenClaw, and the adapter reference.
Every gbrain tool error is one content block holding a JSON envelope. Read
code (an older server sends only error), then follow fix.next:
run: callfix.mcp(or runfix.argvwhere you have a shell) exactly as given.ask_user: relayuser_messageand stop; act only after the user agrees.tell_user_to_run: the fix needs the user or the brain host's operator (for example a scope grant or a CLI-only repair); give themfix.command.wait: retry after the stated delay with the same request.report: tell the user what happened; the host operator runsgbrain doctor --json.
Then run fix.verify, which is always read-only. A mutating call with an
unknown outcome points at its write receipt (get_write_request), never at a
blind retry. Successful results can carry extra [gbrain notice …] text blocks
after content[0]; read them too (a degraded notice means an empty result is
not proof the user has no notes). Full contract, including the scope-failure
error/code pairs: AGENT_OPERATOR_v1.
search and query return their rows as compact JSON in the first content
block. Remote callers get lean rows by default: the fields an agent acts
on, without the ranking diagnostics that would make each row several times
longer than its evidence text.
A lean row keeps slug, title, type, chunk_text, score (4
significant digits), effective_date, source_id, chunk_id (with slug
and source_id, the assemble_evidence hit), evidence, create_safety
(the duplicate-page guard), trust_tier and origin. It keeps id (the
fetch key) only when this connection can call fetch at that moment: a
full surface, a stdio session request_tools widened, or an HTTP client
whose surface and scopes include it (starter and verbs do not list
fetch). After fetch becomes callable, re-run search for id or pass
the row's slug to fetch (accepted when unambiguous); fields: "full"
returns every field. It also keeps every safety or
provenance marker that is present: injection_suspected, injection_p,
unverified, content_flag, status, superseded, superseded_by,
message_id, thread_id, source_subject, modality when not text,
stale when true, provenance: "generated" on a machine-written page,
and delivered: {"truncated": true} when evidence delivery cut the text.
effective_date is the page's own date and effective_date_source says
which kind: date, published or filename is a document date,
event_date an event date, and created or fallback only when the page
was created or imported. It is never a contract's effective or validity
date; that date is in the text. Every reply with dated rows adds one line
after the rows that says so ([gbrain dates] ...).
{"query": "acme-example renewal terms"}[{"slug":"contracts/acme-example-msa","title":"MSA: Acme Example","type":"contract","chunk_text":"Payment terms: Net 45. Renewal is annual.","chunk_id":812,"score":0.91,"source_id":"default","effective_date":"2026-04-02","id":"gbrain-page:v1:WyJkZWZhdWx0IiwiY29udHJhY3RzL2FjbWUtZXhhbXBsZS1tc2EiXQ","evidence":"keyword_exact","create_safety":"probable"}]Pass fields: "full" to get every field (page_id, chunk_index,
chunk_source, keyword_hit, cosine, base_score, boosts, rerank and
graph signals, the full delivered object):
{"query": "acme-example renewal terms", "fields": "full"}_meta.retrieval.rows reports "lean" or "full" for every remote call.
| Client | Rows by default | How to get full rows |
|---|---|---|
| Any MCP client (stdio or HTTP) | lean | fields: "full" per call, or the host sets gbrain config set mcp.result_rows full |
| gbrain thin CLI, v0.60.44.0 or later | full (it sends X-Gbrain-Client) |
nothing to do |
| gbrain thin CLI, older than v0.60.44.0 | lean | upgrade the CLI, or the host sets mcp.result_rows full |
Trusted local CLI (gbrain search, gbrain call) |
full | nothing to do |
The host setting is read per request over OAuth HTTP and at start-up for
gbrain serve (stdio), so restart a stdio server after changing it. The
X-Gbrain-Client header selects a row shape only; it is not an identity
claim and never grants access.
Say to your agent: "Search my brain for the acme-example renewal terms and show me every ranking field for the top result."
query can return saved facts as rows of their own, after the page rows and
only in slots and token budget the pages left free. A fact row is not a page.
It has result_type: "fact" and fact_id, and no slug, id, type or
chunk_id, so it can't be passed to get_page, fetch or
assemble_evidence. follow_up names the call that returns the fact:
recall with the fact's entity, or with a grep of its text when it has no
entity. page_slug is present only when the caller can read the entity's page;
pass it to get_page.
{"result_type":"fact","fact_id":"412","page_slug":"companies/acme-example","follow_up":{"op":"recall","args":{"entity":"companies/acme-example"}},"title":"Saved fact about companies/acme-example","chunk_text":"Saved fact (fact; valid from 2026-09-01; provenance: user update): The billing contact for Acme Example is Bob.","score":0.42,"source_id":"default"}search.query_facts_arm=false turns fact rows off.