Use with MCP

LambdaDB can be used from any Model Context Protocol (MCP) client through the LambdaDB MCP server. This makes the knowledge and memory stored in LambdaDB available to AI assistants that need to inspect collections, list documents, fetch records, or run search queries against a project. This guide shows a local setup flow using a project API key, base URL, and project name from LambdaDB Cloud.

Before you start

You will need:

A LambdaDB project API key
Your project’s base URL
Your project name
Node.js 22.14.0 or later and npm
An MCP client such as Claude Desktop

The LambdaDB MCP server is designed to connect to a single LambdaDB project per process. It uses a project-scoped API key and is read-only by default unless write tools are explicitly enabled.

Step 1: Get your LambdaDB connection details

From LambdaDB Cloud, collect the following values for the project you want to expose to your MCP client:

Base URL
Project name
Project API key

Project creation does not automatically issue an API key. In the project’s API Keys tab, an organization Owner or Admin must select Create key and save the full value when it is shown. Use that saved value for the MCP configuration; it cannot be revealed again from the key list. See API key management.

Store your project API key securely. Do not commit it to source control or share it in screenshots, prompts, or logs.

Step 2: Choose the published package

The stable npm package is @functional-systems/lambdadb-mcp@0.1.4. This guide pins that published version. No source checkout or build is required.

node --version
npm view @functional-systems/lambdadb-mcp@0.1.4 version engines

With the required environment variables supplied, an MCP client can launch:

npx --yes @functional-systems/lambdadb-mcp@0.1.4

This is a stdio server: when launched in a terminal it waits for MCP protocol input, rather than showing an interactive prompt. It has no CLI --help or --version mode; use npm metadata to check the package version. Protocol messages use stdout and diagnostics use stderr. The stdio receive buffer is limited to 10 MiB; exceeding it closes the connection. Split large tool inputs into smaller calls. This transport limit does not increase LambdaDB’s API request limits. Alternatively, install the same version globally with npm install --global @functional-systems/lambdadb-mcp@0.1.4 and configure your client to run lambdadb-mcp with no arguments. Installed copies do not update themselves. To update a global install, run npm install --global @functional-systems/lambdadb-mcp@latest; to remove it, run npm uninstall --global @functional-systems/lambdadb-mcp. For pinned client configurations, review releases and change the version explicitly. @dev is an opt-in prerelease channel.

Environment variables

Variable	Meaning
`LAMBDADB_BASE_URL`	Required region-specific API base URL from LambdaDB Cloud
`LAMBDADB_PROJECT_NAME`	Required existing project name
`LAMBDADB_PROJECT_API_KEY`	Required project API key
`LAMBDADB_MCP_ENABLE_WRITE_TOOLS`	Optional; defaults to `false`. Set `true` to expose write tools.

The installed package reads the process environment directly. It does not read the general CLI’s config file or automatically load .env or .env.local. LAMBDADB_ENV_FILE is only for the source repository’s development launchers. Set secrets through your client’s protected local configuration or environment forwarding; do not put the key in command arguments.

Step 3: Add the server to your MCP client

For Claude Desktop, open Settings → Developer → Edit Config and merge this entry into claude_desktop_config.json, preserving existing servers. This uses the official local-server configuration format.

{
  "mcpServers": {
    "lambdadb": {
      "command": "npx",
      "args": ["--yes", "@functional-systems/lambdadb-mcp@0.1.4"],
      "env": {
        "LAMBDADB_BASE_URL": "YOUR_REGION_BASE_URL",
        "LAMBDADB_PROJECT_NAME": "YOUR_PROJECT_NAME",
        "LAMBDADB_PROJECT_API_KEY": "YOUR_PROJECT_API_KEY",
        "LAMBDADB_MCP_ENABLE_WRITE_TOOLS": "false"
      }
    }
  }
}

Replace each placeholder locally. This file contains a credential once filled in: keep it private and out of source control. Do not assume a desktop application inherits variables exported in a terminal. Fully quit and restart Claude Desktop. Other MCP clients can use the same command, arguments, and environment values, but their configuration schema can differ.

Step 4: Verify the connection

Open your client’s server/tool list (in Claude Desktop, Manage connectors → lambdadb). A read-only connection should advertise these five tools:

lambdadb_list_collections
lambdadb_get_collection
lambdadb_query_collection
lambdadb_list_docs
lambdadb_fetch_docs

Tool discovery confirms the local MCP connection; it does not authenticate to LambdaDB. To check project access:

Call lambdadb_list_collections with { "size": 1 } to confirm the project connection.
Call lambdadb_get_collection for a known collection.
Run lambdadb_query_collection with a small query against that collection.

Query, fetch, and list tools accept an optional ref such as { "kind": "tag", "name": "release" }; omitting it reads from main. Strongly consistent reads are available only for query/fetch against a branch directly, including the default main branch. List does not support consistentRead. See Data versioning. For example, pass these arguments to lambdadb_query_collection for the sample collection created in the CLI guide:

{
  "collectionName": "cli-demo-docs",
  "size": 10,
  "query": { "queryString": { "query": "serverless", "defaultField": "text" } },
  "ref": { "kind": "branch", "name": "main" },
  "consistentRead": false
}

The MCP server also accepts keyword facets, an omitted query for match-all, and size: 0 with nonempty facets for counts only.

Native reranking

The MCP server accepts optional rerank on lambdadb_query_collection. For the sample collection above, pass:

{
  "collectionName": "cli-demo-docs",
  "size": 2,
  "query": { "queryString": { "query": "serverless", "defaultField": "text" } },
  "ref": { "kind": "branch", "name": "main" },
  "rerank": {
    "provider": "typesafe",
    "model": "jev-1.13.0",
    "queryText": "Which documents explain serverless search?",
    "fields": ["text"]
  }
}

LambdaDB manages the provider credentials. Omitting rerank or passing null keeps existing search behavior. Applied results preserve the final score, envelope retrievalScore, server order, and top-level rerank metadata, including docsUrl downloads. Check rerank.status before interpreting scores; fallback uses original search scores and exposes no partial reranking scores. See Native reranking for custom criteria, candidate depth, and failure/query restrictions. Reranking is available through the read tool and does not require enabling write tools.

Bayesian hybrid search

The MCP server accepts the Bayesian request through lambdadb_query_collection. Add collectionName for a collection with the example’s body and bodyEmbedding fields. Without reranking, pass top-level candidateSize; with reranking, omit it and use rerank.candidateSize. The read tool preserves result scores and rerank metadata, including downloaded results.

Optional: Enable write tools

The LambdaDB MCP server can also expose write operations such as:

lambdadb_create_collection
lambdadb_upsert_docs
lambdadb_delete_docs

The MCP server accepts all 49 fixed text analyzer presets when creating collections. The create tool accepts an embedding block in indexConfigs for native embeddings. The MCP server has no collection-schema update tool. Upsert and delete accept an optional branch; omitting it writes to main. Creating a collection requires nonempty indexConfigs. Deleting documents requires exactly one of a nonempty ids array or a filter. To enable them, change the environment value and restart the MCP server:

LAMBDADB_MCP_ENABLE_WRITE_TOOLS=true

Enable write tools only in environments where document creation, updates, and deletion are intended. Start with a non-production project when testing write access from an MCP client.

Successful writes are accepted before committed search visibility is verified. Confirm expected documents with subsequent reads; tool success alone is not an indexing readiness check.

Troubleshooting

If the server starts but tools fail:

Verify that base URL, project name, and project API key all belong to the same LambdaDB project.
Confirm that the project API key is still valid.
Check the MCP client logs for startup or tool-call errors.
Run the server locally first to make sure the process starts with the expected environment variables.

If tools are missing:

Confirm that the client launches the pinned npm package or the intended installed executable.
Restart the MCP client after editing its configuration.
If you expect write tools, make sure LAMBDADB_MCP_ENABLE_WRITE_TOOLS=true is set.

If the server cannot start:

Check that the Node executable visible to the client is version 22.14.0 or newer, and that npx is on its PATH. For ENOENT, use the absolute path returned by command -v npx on macOS/Linux or where npx on Windows, and ensure Node is also reachable.
A missing-variable error means the required values were not supplied to the child process. Editing a checkout’s .env.local does not configure an npm-launched server.
Use true or false for write opt-in; an invalid boolean fails startup.
Check npm/network errors if the pinned package cannot be downloaded. Check JSON syntax and restart the server after configuration changes.
On macOS, Claude Desktop logs are under ~/Library/Logs/Claude; on Windows, %APPDATA%\Claude\logs. Inspect mcp.log and mcp-server-lambdadb.log locally, without sharing credentials or document data.

Optional: Build from source

For development, use a release tag and Node.js 22.14.0 or later:

git clone --branch v0.1.4 https://github.com/lambdadb/lambdadb-mcp
cd lambdadb-mcp
npm ci
npm run build
cp .env.example .env.local

Fill in .env.local locally, then run npm run start:env. The source launcher selects LAMBDADB_ENV_FILE when set, otherwise .env.local if present, otherwise .env. Exported values take precedence. Direct node dist/index.js does not load these files. See the repository README for development and Inspector usage.

Next steps

Learn how to create collections in Create a collection
Learn how to list documents in List data
Learn how to search collections in Search overview

Get started

Migrations

Collections

Data versioning

Documents

Search

Manage Costs

Security

Before you start

Step 1: Get your LambdaDB connection details

Step 2: Choose the published package

Environment variables

Step 3: Add the server to your MCP client

Step 4: Verify the connection

Native reranking

Bayesian hybrid search

Optional: Enable write tools

Troubleshooting

Optional: Build from source

Next steps

​Before you start

​Step 1: Get your LambdaDB connection details

​Step 2: Choose the published package

​Environment variables

​Step 3: Add the server to your MCP client

​Step 4: Verify the connection

​Native reranking

​Bayesian hybrid search

​Optional: Enable write tools

​Troubleshooting

​Optional: Build from source

​Next steps

Before you start

Step 1: Get your LambdaDB connection details

Step 2: Choose the published package

Environment variables

Step 3: Add the server to your MCP client

Step 4: Verify the connection

Native reranking

Bayesian hybrid search

Optional: Enable write tools

Troubleshooting

Optional: Build from source

Next steps