// one endpoint, one header
The gitian MCP server
A knowledge base your agent writes to over the Model Context Protocol. Streamable HTTP at a single stateless endpoint, authenticated with one header, discoverable from its own 401. Connect a compliant client with nothing configured but the URL. There's no session to manage, no token to paste, no out-of-band setup.
// shape
Stateless on purpose
Every call is a self-contained POST to one path. There is no session to establish, resume, or leak. A serverless deployment scales horizontally with no sticky routing, and a client that crashes mid-conversation simply calls again.
POST https://gitian.dev/api/mcp
Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json, text/event-streamEvery successful response carries an envelope alongside the tool's own result. The field worth building against is vocab_rev: an owner-scoped monotonic counter that acts as an ETag on the topic vocabulary. It is fetched in parallel with the tool's own query, so it costs no extra round trip, and it bumps only when a topic or category definition changes. It does not bump on usage drift. A client that sees it change should re-read the vocabulary before its next publish; a client that sees it steady can skip that read entirely.
Warnings are advisory and never fail a write: a link projection that couldn't be rewritten, a novel topic that was auto-minted, a category slug that doesn't exist yet, a doc that landed with no topics. Errors are typed rather than numeric, so a client can branch on the failure instead of parsing a message.
// auth
Discoverable from its own 401
An unauthenticated call doesn't just fail — it answers with a WWW-Authenticate header pointing at the protected-resource metadata. From that one response an OAuth-aware client finds the authorization server, registers itself, and starts a consent flow. Nothing about this needs to be configured by hand: the correct amount of setup for a remote MCP server is the URL.
# the discovery chain, all from a single 401
401 WWW-Authenticate: Bearer resource_metadata="…"
→ /.well-known/oauth-protected-resource
→ /.well-known/oauth-authorization-server
→ /oauth/register (dynamic client registration)
→ /oauth/authorize (consent, in the browser)
→ /oauth/token (code + PKCE verifier)Authorization code with mandatory PKCE — there is no path that skips the challenge. Dynamic client registration accepts public clients only and never issues a client secret, because a locally-installed agent cannot keep one. Revocation is a real endpoint, and every connection a user has approved is listed and individually revocable under Connected agents in settings; the next call after a revoke re-prompts.
Tokens for places without a browser
CI has nothing to complete a consent screen in, so personal access tokens remain a first-class path. They're minted in settings, carry a gkb_ prefix so a leaked one is recognizable on sight, and only their SHA-256 hash is ever stored. The token itself is shown once and never again.
claude mcp add --transport http gitian https://gitian.dev/api/mcp \
--header "Authorization: Bearer gkb_…"Worth knowing if you're wiring this yourself: a statically configured Authorization header is authoritative and suppresses the OAuth flow. That is why the plugin ships no header at all. Leaving it out is exactly what makes "install, connect" a browser-based flow with nothing to paste.
// tools
Grouped by the job, not by the table
The surface is organized around what an agent is trying to do at a given moment. Names are stable; the set grows, so treat the discovery response as authoritative rather than hard-coding a list.
| orient | search full-text, list by facet, neighbors for what relates to what, topic for a hub view with degree and co-topics, file_intents for who else is touching these paths, history for a slug's revisions. |
|---|---|
| read | get a slug, optionally at a specific revision. |
| publish | publish_doc, publish_memory, publish_entry: full-document writes, one per primitive. |
| revise | append_entry creates-or-appends a journal entry and union-merges its list fields; retract_item tombstones a slug without destroying its history. |
| curate | publish_topic and retract_topic maintain the vocabulary. Neither grants curated trust on its own. Promotion is deliberately a human act in the UI. |
The tools teach their own formats
Rather than making a client guess at manifest shapes, the server exposes them as MCP resources: a set of gitian-kb://format/* guides, one per primitive plus a shared conventions document, and a live gitian-kb://vocab listing every active topic and category. An agent reads the vocabulary before it links or mints, which is what keeps a shared vocabulary from fragmenting into forty near-synonyms.
The live resources are authoritative over any schema a client has cached. If a write is rejected for a field your cached schema doesn't list, trust the server and retry. The full contract, including headers, the error envelope, and portability notes, is documented in the repository as the transport spec.
// connect
Two commands for the paved path
claude plugin marketplace add GitianDocs/gitian-tools
claude plugin install gitian-kb@gitian-toolsThe plugin carries the wiring plus the discipline that makes the corpus worth reading: guidance on when and what to publish, a session hook that preloads repo, branch and date, a pre-compaction handoff command, and a librarian subagent bounded by hard rules — it never authors body content and never chooses topics, because a doc's value is that the author was there. Two siblings ride the same connection: gitian-docs keeps annotations and paired docs in sync, and gitian-spec turns a spec request into a knowledge-base doc instead of a loose markdown file.
Nothing here is Claude-specific at the protocol level. Any MCP client that speaks streamable HTTP and handles a 401 with discovery metadata can connect to the same endpoint with the same header.
// questions
Questions people actually ask
Do I need to paste an API key to connect?
No. A compliant client discovers the OAuth server from the 401 it gets on its first call, registers itself dynamically, and opens your browser for consent. Tokens are only needed where there is no browser, such as CI.
Is this a local stdio server or a remote one?
Remote, over streamable HTTP at a single endpoint. There is no local process to supervise and no session state to keep, so a client can reconnect at any point without resuming anything.
Does it work with MCP clients other than Claude Code?
Yes at the protocol level. Any client that speaks streamable HTTP, sends a bearer token, and follows discovery metadata from a 401 can connect. The plugin is a convenience for one client, not the interface.
How does a client know when to re-read the vocabulary?
Every response carries vocab_rev, an owner-scoped counter that changes only when a topic or category definition changes. Re-read when it moves; skip the read when it doesn't.
Can I revoke an agent's access without rotating anything else?
Yes. Each approved connection is listed separately under Connected agents and can be revoked on its own; the next call from that client re-prompts for consent. Personal access tokens are revoked the same way, individually.
Why is PKCE mandatory rather than optional?
Because every client here is a public client. A locally installed agent cannot keep a secret. Dynamic registration therefore never issues one, and PKCE is what takes its place as proof that the client redeeming the code is the one that requested it.
// how this page is found
This route's own index plan
This is the page most likely to earn a link rather than a click — MCP server directories, ecosystem lists, and "how do I do OAuth for a remote MCP server" write-ups all want something concrete to point at. That makes it the cluster's authority sink: inbound links land here and flow onward to /memory.
Title and description
The phrases this page is built to own
remote MCP server OAuth, MCP dynamic client registration, MCP streamable HTTP example, MCP server bearer token auth, MCP knowledge base server. These are documentation-shaped queries from developers, which is the one audience segment where a small product competes on equal terms. Nobody outranks a page that actually answers the question.
Structured data and the copy rule
TechArticle plus BreadcrumbList and the FAQ as FAQPage, referencing the site-wide Organization and SoftwareApplication by id. The standing rule applies hardest here: never print a tool count in indexed text. It changes with every release, and a stale numeral in a snippet is worse than no numeral. Name the families and the verbs instead — publish, read, revise, curate.