MCP server — @lbb/mcp

@lbb/mcp is an MCP server that gives an agent a small, graph-aware tool belt over a little big brain server. It wraps the @lbb/client SDK and ships two ways: a local stdio shim (npx @lbb/mcp) and a hosted streamable-HTTP endpoint with OAuth sign-in.

Six task-shaped tools

The tool belt is agent-shaped — task tools, not one tool per HTTP route:

Tool	Purpose
lbb_search	natural-language retrieval, multi-query fusion, optional text-seeded path following
lbb_inspect	graph context and exact reads: guide, ontology, RDF/SHACL schema, stored rules, metadata, entity, state, history, why, traverse
lbb_query	analytical/expert reads: structured query, SPARQL text, SHACL, inference, retrieval premises, canned analysis
lbb_commit	write triplets, embeddings, or entity properties
lbb_configure	define a new graph ontology, publish a previewed RDF/SHACL schema, or replace stored inference rules
lbb_index	refresh persisted BM25, vector, and adjacency indexes

Read tools accept detail: "compact" | "standard" | "full" and default to compact structured envelopes: {summary, data, counts?, truncated?, rows_shown?, next?}.

Local (stdio) — Claude Code, Cursor, Codex

Add to your editor’s MCP config (.mcp.json / mcp.json):

{
  "mcpServers": {
    "lbb": {
      "command": "npx",
      "args": ["-y", "@lbb/mcp"],
      "env": {
        "LBB_BASE_URL": "https://db.eu.littlebigbrain.com",
        "LBB_API_KEY": "lbb_sk_live_…"
      }
    }
  }
}

Set LBB_GRAPH / LBB_BRANCH to target a graph/branch other than main. (When a self-hosted server is available, you’ll point LBB_BASE_URL at it and use its token instead.)

Hosted (streamable-HTTP, OAuth)

The hosted endpoint at https://mcp.littlebigbrain.com is authenticated with native MCP OAuth — there is no static bearer key. It is an OAuth 2.1 protected resource, so signing in to your account authorizes the connection. Claude-style clients use the per-stack URL:

{
  "mcpServers": {
    "lbb": {
      "url": "https://mcp.littlebigbrain.com/mcp/<your-stack-slug>"
    }
  }
}

A client that supports remote auth discovers the flow automatically: it receives an authorization challenge, runs the browser sign-in, and presents the resulting access token. The endpoint validates the token, confirms your account owns the stack, mints a short-lived data-plane session, and runs the tools scoped to that stack — your machine never holds a little big brain key. Add ?graph=/?branch= to target a graph/branch other than main.

Codex Desktop

Codex sends the MCP URL as an OAuth resource parameter and also appends any configured oauth_resource, producing a duplicate resource query the authorization server rejects. For Codex, use the MCP origin as the URL and pass the stack in a header; do not set oauth_resource:

{
  "mcpServers": {
    "lbb": {
      "type": "http",
      "url": "https://mcp.littlebigbrain.com",
      "headers": { "X-LBB-Stack": "<your-stack-slug>" }
    }
  }
}

When self-hosting is available, the same tools will also be servable over streamable-HTTP with a simple key bearer for use behind your own auth — but for now, the hosted endpoint above is the way to connect an agent.

Create a typed graph for the agent

lbb_configure with action: "define_ontology" creates a new graph with a custom ontology (the ontology is fixed at graph creation). Give it entity-type and relation names and little big brain fills in ids and sensible defaults:

// lbb_configure
{
  "action": "define_ontology",
  "graph": "support",
  "entity_types": [{ "name": "Customer" }, { "name": "Ticket" }],
  "relations": [
    { "name": "OPENED", "source": ["Customer"], "target": ["Ticket"], "reducer": "append_only" }
  ]
}

Then lbb_commit typed facts against the new graph and lbb_inspect with action: "ontology" to confirm the vocabulary. For an existing standard ontology, pass a raw source document with format (turtle, json_ld, rdf_xml, csv, tsv, or lbb_json; omit or auto to auto-detect).

Querying: structured, SPARQL, SHACL, inference

Three complementary surfaces sit over the object-storage permutation view:

• lbb_query mode structured — a SPARQL-subset SELECT/ASK over a conjunctive basic graph pattern (patterns) with filters (typed-literal FILTER), group_by + aggregates (COUNT/SUM/AVG/MIN/MAX), having, order_by, and as_of_valid_time. A filters/having entry has the shape { compare: { op: eq|ne|lt|le|gt|ge, left, right } } (or and/or/not), where each operand is { var }, { property: { var, field } }, or a typed { value: { str | i64 | f64 | bool | date_time | entity } }. GROUP BY keys can be a typed scalar attribute ({ property: { var, field, as } }) or a calendar bucket ({ date_bucket: { var, field, granularity, as } }), so “commits per area per month” is one server-side query:

  {
    "patterns": [{ "subject": { "var": "c" }, "predicate": "committed_to", "object": { "var": "repo" } }],
    "group_keys": [
      { "date_bucket": { "var": "c", "field": "committed_at", "granularity": "month", "as": "m" } },
      { "property": { "var": "c", "field": "area", "as": "area" } }
    ],
    "aggregates": [{ "func": "count", "as": "n" }],
    "order_by": [{ "var": "m" }]
  }

• lbb_query mode shacl — evaluates node shapes: shacl_mode: select returns matching focus nodes, shacl_mode: validate returns a conformance report. Home of property paths (inverse, sequence, alternative, one_or_more/zero_or_more/zero_or_one), literal constraints, unique keys, closed nodes, and logical and/or/not/xone.

• lbb_query mode infer — runs SHACL-AF inference rules to a bounded fixpoint and previews the derived edges (never written). lbb_configure action define_rules stores a rule set so SHACL include_derived can validate/select over inferred facts.

Lowercase IRIs

SPARQL text (mode: "sparql") addresses relations/types/properties as <https://littlebigbrain.com/{r,class,p}/name>, always lowercase. The tool auto-lowercases little big brain IRI local names for you and reports each rewrite under notes, so a stray uppercase resolves instead of silently matching nothing.

Paging and large results

Query row volume is controlled by row_limit plus cursor paging. Tabular lbb_query responses include row_page: {returned, total, offset, limit, has_more, next_offset?}. When a page is partial, summary says returned X of Y rows and next contains a cursor; pass it back to continue without hand-writing LIMIT/OFFSET. Cursor continuation reuses the original query and pins every page to the head commit observed on page 1, so live writes between pages cannot shift the slicing. lbb_inspect action=entity samples incoming/outgoing/ history to the detail cap while counts holds true totals; a high-degree node carries an edge_sample block with runnable paged reads so reading every edge of a supernode is discoverable in-band.

Self-correcting errors

All server LbbError fields survive the MCP boundary in structuredContent.error. A graph-scope 404 (a raw object-key “not found”) is rewritten into an actionable message that lists the tenant’s real graphs — or, when the graph exists but the branch does not, its real branches — and tells you which graph=/branch= to pass.

Idempotency defaults

When lbb_commit omits idempotency_key, MCP derives one from the graph, branch, and payload; intentionally repeating an identical commit within the retention window requires an explicit different key. MCP defaults edge_idempotency to append (new evidence on an existing edge is recorded); pass edge_idempotency: "skip_unchanged" for re-runnable backfills.

Operator vs. agent surface

Operator-only actions (index GC, compaction, storage inspection) are intentionally left to the CLI, not the agent tool belt.

For end-to-end walkthroughs driven by these tools, see agent long-term memory and migrating a markdown knowledge base.