Endpoints

Endpoints

Two plain HTTP routes sit beside the MCP transport at /mcp, outside the protocol on purpose: checking whether a pod is serving what it should needs curl, not an MCP client. A third serves this document.

Nothing here is authenticated. There is no auth on this server at all — every skill it serves is public markdown — so there is no credential to gate a description of it behind. What that means operationally is in Operations.

Route	Does
GET /health	what this pod is serving, and which sources loaded
POST /reindex	rebuild every source now
GET /openapi.yaml	this surface as OpenAPI 3.1.0, built per process

Servers

URL	Is
http://mcp-kb.flow.svc.cluster.local:8000	In-cluster Service.
http://localhost:8000	docker compose.

GET /health

Readiness, and the fastest way to see which fetches loaded.

Ignores X-Skill-Library: an operator asking what this pod serves wants the real catalogue, not one client's scoped view of it.

curl $MCP_KB/health

Status	Body	Means
200	Health	The catalogue this pod is serving right now.

POST /reindex

Rebuild every fetch now.

Re-reads exactly the fetches the config's plugins and marketplaces name — what the background refresh loop would do on its own — and returns /health plus rebuilt. Takes no input and needs no authorisation beyond what the config has already decided.

curl -X POST $MCP_KB/reindex

Status	Body	Means
200	Reindex	The catalogue after the rebuild.
500	ReindexError	The rebuild raised something no fetch's own failure handling turned into a stale or failed record.

Schemas

Health

Always 200: a fetch or a plugin that failed to load is reported inside fetches and plugins, never raised as a failed request.

Field	Type	Always	Means
status	ok	yes
generation	integer	yes	Rebuilds served since the process started, from 0.
built	string	yes	When the current snapshot was assembled.
skills	integer	yes	Skills in the current index.
prompts	integer	yes	Prompts currently served.
libraries	object of LibraryStatus	yes	One entry per configured library, keyed by name.
plugins	object of PluginStatus	yes	One entry per plugin, declared or read out of a marketplace, keyed by id.
fetches	object of FetchStatus	yes	One entry per materialised tree, keyed by fetch key.

Reindex

Field	Type	Always	Means
status	ok	yes
generation	integer	yes	Rebuilds served since the process started, from 0.
built	string	yes	When the current snapshot was assembled.
skills	integer	yes	Skills in the current index.
prompts	integer	yes	Prompts currently served.
libraries	object of LibraryStatus	yes	One entry per configured library, keyed by name.
plugins	object of PluginStatus	yes	One entry per plugin, declared or read out of a marketplace, keyed by id.
fetches	object of FetchStatus	yes	One entry per materialised tree, keyed by fetch key.
rebuilt	list of string	yes	Fetch keys rebuilt this pass — every fetch, since this endpoint always forces one, whether or not its content moved.

ReindexError

Field	Type	Always	Means
status	error	yes
error	string	yes	A fixed message: a refresh raised outside build_fetch's own per-fetch failure handling — the one case this manual recovery lever can still fail at. The exception itself, with its traceback, goes to the server log, never this body.

LibraryStatus

One configured library, keyed under libraries by its name. The counts are what it serves right now, summed over its plugins.

Field	Type	Always	Means
description	string	yes	The library's description, from the config.
plugins	list of string	yes	The plugin ids this library resolved to: its marketplace's entries, then its plugins:, then its selector's matches.
skills	integer	yes	Skills served in this library.
prompts	integer	yes	Prompts served in this library.
files	integer	yes	Library-level files served in this library.
error	string	no	Present when part of the library could not be resolved — its marketplace could not be read, or a named plugin does not exist. The rest of the library serves.
skipped	list of object	no	Present when the library's marketplace lists entries this server does not install: npm, archive and command sources, strict: false entries, and entries that are malformed.
conflicts	object of string	no	Present when a plugin of this library would serve an address or a prompt name an earlier plugin of it already serves. Keyed by plugin id; that plugin is not served in this library, and serves normally in any other.

PluginStatus

One plugin, keyed under plugins by its id: its config name, or <entry>@<library> for a marketplace entry. skills, prompts, files and built are the plugin's own harvest, independent of which libraries serve it, and are absent when status is failed.

Field	Type	Always	Means
status	string	yes
fetch	string	yes	The key of the fetch this plugin is read from.
root	string	yes	The plugin's directory inside its fetch; empty at the tree's root.
category	string	yes	The plugin's category, or null when it declares none.
tags	list of string	yes
keywords	list of string	yes
version	string	no	Present when the plugin declares one.
libraries	list of string	yes	The libraries that serve this plugin, in config order.
skills	integer	no	Skills this plugin yields.
prompts	integer	no	Prompts this plugin yields.
files	integer	no	Library-level files this plugin yields.
built	string	no	When this plugin was last harvested.
error	string	no	Present when failed: its fetch failed, its directory is not in the tree, or its manifest does not parse.
skipped	list of object	no	Present when this plugin ships something the address space has no room for. Each entry is left out while the rest of the plugin serves: a library file whose address lies inside one of the plugin's own skills or is named _index.md or _files.md; a skill whose frontmatter name breaks the Agent Skills naming rule or differs from its directory, or that a skill before it already serves at that address; a prompt whose name a prompt before it already has, or whose file does not parse or cannot be read. A clash with another plugin is not listed here: it fails the later plugin in that library instead, under the library's conflicts.

FetchStatus

One materialised tree, keyed under fetches by its fetch key — the plugin address without its subdirectory. built and fingerprint describe the tree being served and are absent only when status is failed. live, revalidated, fetched and cooling appear only for a cache: live source — one that revalidates files against a WebDAV server between harvests.

Field	Type	Always	Means
status	string	yes
built	string	no	When the tree served was materialised. Unchanged while stale: a failed refresh does not touch what is on disk.
fingerprint	object	no	A cheap summary of the tree, which a refresh re-takes and compares to decide whether to rebuild. Its keys are the backend's own and are not a contract: a file:// fetch counts files and bytes and takes the newest mtime, git reports the exported commit with the ref it was resolved from and the remote tip that ref names now, WebDAV the exported and remote ETag digests with a file count for each.
live	boolean	no	Present and true only for a cache: live source, whether or not a read has happened yet.
error	string	no	Present when stale (why the last refresh failed, while the previous good tree keeps serving) or failed (why nothing was ever materialised).
revalidated	integer	no	Live fetches only: files priced against the server since this snapshot was built.
fetched	integer	no	Live fetches only: of those, the ones that had moved and were downloaded again.
cooling	boolean	no	Live fetches only: present and true while a failed revalidation has this fetch's reads suspended.

---

Home · Installing · Deployment · Operations