Configuration

Configuration

The config file says what to serve. Environment variables and flags say how to run — transport, port, cache directory — and the two never overlap; those are in Deployment. A key this page does not list is an error rather than a value quietly ignored, because a config that serves nothing is the worst failure a config file has.

mcp-kb schema prints this as JSON Schema, and config.schema.json in the repository is the same document, so an editor with # yaml-language-server: $schema=… at the top of the file completes and validates as you type.

What a backend does with these fields is Sources; what a plugin address and a library select is Plugins.

URL scheme → backend

A source's url decides which backend reads it. There is no kind: field to set and no way to override it.

URL scheme	Backend
git+https://	git
git+http://	git
git+file://	git
webdav+https://	webdav
webdav+http://	webdav
file://	file

Config

The whole config file: the sources, the plugins under them, the libraries.

Field	Type	Required	Default
sources	list of SourceConfig	no	—
plugins	list of PluginConfig	no	—
libraries	list of LibraryConfig	no	—

SourceConfig

A named backend: where bytes come from and how to log in, declared once.

Field	Type	Required	Default	Notes
name	string	yes	—	matches ^[a-z0-9]([a-z0-9-]{0,62}[a-z0-9])?$
url	string	yes	—
auth	BasicAuth	no	—
cache	string	no	snapshot	one of snapshot, live
refresh	string	no	—	matches ^[1-9]\d*[smh]$

PluginConfig

A folder of skills and prompts: a path under a source, plus its metadata.

The metadata fields are Claude's marketplace-entry fields, so a plugin declared here and one read out of a marketplace.json carry the same shape and a selector cannot tell them apart. The glob lists are this server's own: omitted, a kind falls to the plugin's manifest and then to the conventions.

Field	Type	Required	Default	Notes
name	string	yes	—	matches ^[a-z0-9]([a-z0-9-]{0,62}[a-z0-9])?$
description	string	no	""
category	string	no	—
tags	list of string	no	—
keywords	list of string	no	—
version	string	no	—
source	string	yes	—
skills	list of string	no	—
prompts	list of string	no	—
files	list of string	no	—
dialect	string	no	auto	one of auto, mcp-kb, claude, copilot

LibraryConfig

A library: a marketplace, plugins by name, or a query — and their union.

A library carries no tags and no category of its own. Tagging is what a plugin does, so ?tags= reaches a library only through what its plugins say, and the selector gets an unambiguous name of its own after Kubernetes' selector.

Field	Type	Required	Default	Notes
name	string	yes	—	matches ^[a-z0-9]([a-z0-9-]{0,62}[a-z0-9])?$
description	string	no	""
source	string	no	—
plugins	list of string	no	—
pluginSelector	Selector	no	—

Selector

A query over plugins: categories narrow first, then tag groups.

Across the two fields it is AND, as in every faceted search. Within categories it can only be OR — a plugin has exactly one category — and within tags a comma means all of while separate items mean any of, which is the same comma rule a request's ?tags= carries.

Field	Type	Required	Default
categories	list of string	no	—
tags	list of string	no	—

BasicAuth

Credentials for a remote that requires them: a git host, a WebDAV server.

The username is usually a literal — GitHub wants x-access-token — so it takes one. But a service account's name arrives in the same secret as its password, and writing it out here as well is how the two drift apart the day the account is recreated, so it takes an {env:} reference too.

Field	Type	Required	Default
username	EnvRef or string	yes	—
password	EnvRef	yes	—

EnvRef

A secret named by the environment variable that holds it.

Field	Type	Required	Default
env	string	yes	—

Omitting skills, prompts or files is not the same as emptying it

The three glob lists have three states, and the table can only show two of them. A list that is there is the whole answer for that kind. A list that is absent falls through: to what the plugin's own plugin.json declares, and then to the conventions in Plugins. An empty list is an answer too — serve none of that kind.

So prompts: [] is how a repository of skills stops offering the prompts/ directory it keeps for its own development, and leaving prompts out entirely is how you say "whatever this plugin publishes". They read alike and mean opposite things, which is worth knowing before spending an afternoon on why a file appeared.

A library selects one way, and source is not one of the two

source on a library makes it a marketplace library: the catalogue published there is its shape, and plugins: may add beside it. A pluginSelector is a query over every plugin the config knows. Asking for both at once is refused at load, naming the library, because a marketplace library's shape is the catalogue's and a query would have to run before the catalogue had been read.

A library that selects nothing at all — no source, no plugins, no pluginSelector — is refused for the same reason: it is a name with nothing behind it, and a config that serves nothing should say so at boot rather than at the first read.

---

Home · Installing · Deployment · Sources · Plugins