@littlebigbrain/mcp

@littlebigbrain/mcp

Model Context Protocol (MCP) server for little big brain, a search platform for AI applications such as chatbots, search tools, and agents.

Connect an MCP client to search your data, follow relationships, and read the facts behind an answer. The tools also let you load data and define validation rules.

Documentation · Quickstart · Issues

Connect

Create a stack in the console, then choose a hosted connection or a local process.

Hosted connection

For clients that support remote MCP with OAuth, use this URL and sign in with your little big brain account. Replace <stack-slug> with your stack's slug:

https://mcp.littlebigbrain.com/mcp/<stack-slug>

For clients that use an mcpServers JSON configuration:

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

This connection uses account sign-in and does not require a stack API key. The connection guide includes client-specific setup, including the origin URL and X-LBB-Stack header for Codex.

Local process

Requires Node.js 18+. Copy the complete endpoint and a stack API key from Connect in the console, then add them to your client's MCP configuration:

{
  "mcpServers": {
    "lbb": {
      "command": "npx",
      "args": ["-y", "@littlebigbrain/mcp"],
      "env": {
        "LBB_BASE_URL": "https://<your-complete-stack-host>",
        "LBB_API_KEY": "<your-stack-api-key>"
      }
    }
  }
}

The client starts the server and communicates through standard input and output (stdio). Keep the key in your local configuration. Set LBB_GRAPH to change the default graph from main.

A call that deletes or removes data asks you to approve it in the client. A client that cannot show the question gets the error approval_required, and nothing is sent. Set LBB_MCP_DESTRUCTIVE=allow in the server's environment to run such calls without a question.

Run a first query

This example stores three facts in a graph named quickstart: a service writes to a database, and each has a label. The graph is created on its first write.

Ask your client to call lbb_rdf with these arguments:

{
  "action": "import",
  "graph": "quickstart",
  "format": "ntriples",
  "source": "<https://example.org/auth-service> <https://example.org/writesTo> <https://example.org/user-db> .\n<https://example.org/auth-service> <http://www.w3.org/2000/01/rdf-schema#label> \"Auth Service\" .\n<https://example.org/user-db> <http://www.w3.org/2000/01/rdf-schema#label> \"User Database\" .",
  "idempotency_key": "mcp-quickstart-v1"
}

Now ask which database does Auth Service write to? The lbb_query call is:

{
  "mode": "sparql",
  "graph": "quickstart",
  "consistency": "strong",
  "query": "SELECT ?database WHERE { <https://example.org/auth-service> <https://example.org/writesTo> ?db . ?db <http://www.w3.org/2000/01/rdf-schema#label> ?database } ORDER BY ?database LIMIT 10"
}

The result contains one row on a fresh graph:

The query follows a stored relationship to its database label. Strong consistency lets it read the import without waiting for a background index job.

An agent without a SPARQL query can pass the question in plain words:

{
  "mode": "question",
  "graph": "quickstart",
  "question": "Which database does Auth Service write to?"
}

The server answers in plain words (POST /v1/query/ask). A router model picks the kind of question. A reasoning model runs queries in a bounded loop, reads their rows, and answers. The result holds answer (text, citations, the IRIs the answer names, and chart, how to draw the rows, when the server gave one), steps, the route, and the query and rows the answer stands on. next continues that query with mode: "sparql". A question takes about 8 s. Each question uses model tokens and counts toward a daily limit of the stack, so the tool does not retry a failed call.

The server finds the names in the question in the graph and lists them in linked. When the question is about records you already know, pass their IRIs in anchor (at most 10): the queries use them directly. A question about a date reads the last commit written by the end of that day; pass timeline ([{date, as_of_commit_seq, label?}]) when the commits stand for other dates. A question that asks what changed returns history.added, history.removed and history.changed, with history.totals.

When the tool call carries a _meta.progressToken, the server sends a progress notification for each step, for example Route: lookup (router, 0.92) or Step 2, sparql SELECT ?db: 1 row. The result is the same. Cancel the call to stop the server's work.

To write the queries yourself, use names, describe, commit_at and compare, then mode: "sparql".

For your own data, start with lbb_inspect using action: "guide" or action: "ontology". Imported Resource Description Framework (RDF) data keeps its original identifiers; inspect it with SPARQL when choosing query predicates.

Tools

See search by meaning for embedding setup. To define constraints with the Shapes Constraint Language (SHACL), see query and validation.

RDF imports and JSON facts use different write workflows. A graph first written through lbb_rdf does not accept JSON fact writes through lbb_commit. Choose the workflow when creating the graph. RDF updates support additive INSERT DATA; see the RDF guide for format and update limits.

Pages and saved queries

When a result includes next, pass those arguments to the same tool to read the next page. Continue until next is absent. row_limit sets a maximum; large values can make a page shorter.

SPARQL queries keep the same commit across pages. Save the query and its returned commit sequence to check an answer later, then use as_of_commit_seq to select that version. See history and replay for retention and evidence handling.

Embed the server

To serve the tools from your own Node.js process:

import { createMcpHttpServer } from "@littlebigbrain/mcp";

createMcpHttpServer({
  baseUrl: process.env.LBB_BASE_URL!,
  mcpPath: "/mcp",
  allowedHosts: ["127.0.0.1", "localhost", "::1"],
}).listen(8080, "127.0.0.1");

Clients connect to http://127.0.0.1:8080/mcp and send a stack API key in Authorization: Bearer <key>. See the Node.js integration guide for HTTP options and integration with an existing MCP server.

Development

From a clone of this repository:

npm ci
npm run build
npm run typecheck
npm test

License

Apache-2.0.