API reference

Bourdon has three programmable surfaces, and all three are documented here. Which one you use depends on where you are standing.

MCP server#

bourdon serve                                  # stdio, for a client that launches the server
bourdon serve --transport http --port 7500     # HTTP, loopback only by default

Transports#

stdio is the MCP default and the zero-config path: the client launches bourdon serve and talks to it over standard input and output. There are no ports and no tokens because the caller is your own process; it gets the trusted operator identity.

HTTP serves the MCP endpoint at /mcp on port 7500. Binding anything other than loopback requires authentication to be configured, or the server refuses to start:

bourdon agent add my-laptop --tier trusted       # prints a bearer token once
bourdon serve --transport http --host 0.0.0.0 --allowed-host bourdon.example.org

Clients present the token as Authorization: Bearer <token>:

{
  "mcpServers": {
    "bourdon": {
      "url": "https://bourdon.example.org/mcp",
      "headers": { "Authorization": "Bearer bdn_…" }
    }
  }
}

Requests under a Host header you did not declare are refused with 421 Misdirected Request before authentication, as a DNS-rebinding guard. Declare each public name with --allowed-host or BOURDON_ALLOWED_HOSTS.

OAuth front door#

Browser clients that cannot carry a header (claude.ai custom connectors, ChatGPT connectors) authenticate through a built-in OAuth flow with a consent page you gate with a passphrase. There is no identity provider and no third party in the path.

bourdon oauth set-passphrase
bourdon serve --transport http --oauth-public-url https://bourdon.example.org

Setting --oauth-public-url is what turns it on. The full model, including what it does not promise, is in docs/oauth-security-model.md.

Peers#

bourdon serve --transport http --peer https://other-machine.example/ --federate

--peer names one peer (repeatable). --federate also loads ~/.bourdon/peers.yaml. --no-peers forbids federation entirely. Remote peers must be HTTPS. See How federation works for the semantics.

Tools and resources#

Sixteen tools and three resources. They are listed with full signatures on MCP tools, a page generated from the server source at each release. The short map:

Every read takes access_level (public, team, or private, default public for reads and team for recognition). Every write is validated against the L5 schema before it lands.

Command line#

bourdon --help is authoritative and every subcommand has its own --help. Grouped by job:

Install and check#

Publish memory#

Read memory#

Serve and secure#

Move memory#

Surfaces#

Stable contracts#

These are the shapes other software can depend on. Everything else may change before 1.0; see Status and stability.

The CLI, the L5 wire format, the spec, and the conformance fixtures are Apache-2.0. The engine behind them is BUSL-1.1 and converts to Apache-2.0 four years after each release. Details in LICENSING.md.