MCP server — @littlebigbrain/mcp

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

Source and issues: github.com/littlebigbrains/lbb-mcp (Apache-2.0).

Task-shaped tools

The set has one tool per task rather than one tool per HTTP route. These are the tools for the RDF surface.

Tool	Purpose
lbb_inspect	graph context and exact reads: guide, ontology, ontology conformance, schema, metadata, entity, state, history, why, transitions
lbb_query	analytical reads: structured query, SPARQL text, canned analysis
lbb_commit	write statements or entity properties, and retract them
lbb_branch	branch lifecycle: fork a working branch, then validate and merge it back onto its fork parent as one commit
lbb_configure	define a new graph ontology, evolve it, or atomically publish an ontology and shapes bundle

Use lbb_inspect with action: "ontology" before writing a query or a statement, so the agent chooses only types, relations, and properties present in the pinned generation.

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", "@littlebigbrain/mcp"],
      "env": {
        "LBB_BASE_URL": "https://0abc1def--production.db.eu.littlebigbrain.com",
        "LBB_API_KEY": "lbb_sk_live_…"
      }
    }
  }
}

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

Hosted (streamable-HTTP, OAuth)

The hosted endpoint at https://mcp.littlebigbrain.com is authenticated with native MCP OAuth. 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, issues a short-lived data-plane session, and runs the tools scoped to that stack, so your machine never holds a little big brain key. Add ?graph= or ?branch= to target a graph or 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 that the authorization server rejects. For Codex, use the MCP origin as the URL and pass the stack in a header, and leave oauth_resource unset:

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

For a self-hosted server, the package also serves the same tools over streamable HTTP (npm run start:http, default :8080/mcp) with a key bearer for use behind your own auth. Its edge bounds JSON request bodies to 1 MiB by default, applies a 30-second request timeout, and redacts unexpected internal errors. Use the hosted OAuth endpoint above for multi-tenant connections.

Embed in a Node process

The package entrypoint exposes three supported values: createMcpHttpServer creates the bounded key-bearer HTTP edge, buildLbbServer creates an MCP server bound to an existing LbbClient, and registerLbbTools installs the tools on an existing MCP server.

import {
  createMcpHttpServer,
  type McpHttpServerOptions,
} from "@littlebigbrain/mcp";

const options: McpHttpServerOptions = {
  baseUrl: "https://0abc1def--production.db.eu.littlebigbrain.com",
  mcpPath: "/mcp",
  maxBodyBytes: 1_048_576,
  requestTimeoutMs: 30_000,
  onError: () => console.error("MCP request failed"),
};

createMcpHttpServer(options).listen(8080, "127.0.0.1");

Clients call POST /mcp with JSON and Authorization: Bearer <LBB_API_KEY>; GET /healthz is unauthenticated. Add ?graph= or ?branch= to override the default scope. clientFactory is available for dependency injection. The hosted multi-tenant OAuth edge is part of the API rather than this library surface.

Create a typed graph for the agent

lbb_configure with action: "define_ontology" creates a graph with a custom ontology, and on a graph that already exists it applies an additive difference and does nothing when the ontology already matches. 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 statements 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 it or use auto to auto-detect).

Querying: structured and SPARQL

Two query surfaces run over the published RDF snapshot.

lbb_query mode sparql runs SPARQL 1.1 text (SELECT and ASK).

lbb_query mode structured is a SPARQL-subset SELECT/ASK over a conjunctive basic graph pattern (patterns) with filters (typed-literal FILTER), group_by and aggregates (COUNT/SUM/AVG/MIN/MAX), having, order_by, and as_of_valid_time. A filters or 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" }]
}

Lowercase IRIs

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

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 and 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 returns one bounded entity neighborhood. Use lbb_query in SPARQL mode with a property path for exact multi-hop selection, and lbb_inspect action=history for the entity timeline.

Self-correcting errors

All server LbbError fields are preserved across the MCP boundary in structuredContent.error. A graph-scope 404 (a raw object-key “not found”) is rewritten into an actionable message. That message lists the stack’s real graphs, or its real branches when the graph exists but the branch does not, and names the graph= or branch= value 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, so new evidence on an existing edge is recorded; pass edge_idempotency: "skip_unchanged" for re-runnable backfills.

Operator and agent surfaces

Operator-only actions such as storage inspection stay outside the agent tool set. Published maintenance and garbage collection are automatic and have no public trigger.

For end-to-end walkthroughs driven by these tools, see branch-per-session workspaces and time-travel audit.