Local and offline: the .mcpb

Everything on the other Connect pages uses the hosted server. This page is for running the whole thing yourself: the API, the memory and their databases on your machine, and your client talking to it over stdio. It is for contributors and for anyone who wants their vocabulary to stay on their own disk.

This does not connect to your hosted account

The local server signs in with a fixed token against an API you run, not with OAuth. It cannot reach the profile you built through api.langweave.tech; for that, use the hosted server.

Run the API

You need Node 22.12 or later, pnpm and Docker, and clones of two repositories: langweave and lexmem, which keeps the memory — the catalogs, your words and their states — and runs as its own stack beside this one.

pnpm install && pnpm dev:up                          # in the lexmem clone: the memory on :8090
pnpm install && pnpm dev:up                          # in the langweave clone: the API on :8080
pnpm --filter @langweave/mcp-server enroll es        # choose a language: es or ja

Both local stacks accept the token dev-token, for the same account. Choosing a language matters exactly as it does hosted: until you do, every tool says so.

Connect a client

Claude Desktop (.mcpb)

1. Build the bundle:

   pnpm --filter @langweave/mcp-server pack:mcpb

   It writes packages/mcp-server/mcpb/dist/langweave-<version>.mcpb.

2. Check the bundle before you install it — see below.

3. Open the .mcpb with Claude Desktop (double-click it, or drag it onto Settings → Extensions) and install it. The defaults — API base URL http://localhost:8080, token dev-token, timeout 5000 ms — are the local stack’s; change them only if yours differs.

Any MCP client (stdio)

Point the client at the source, run under tsx, from your clone:

{
  "mcpServers": {
    "langweave": {
      "command": "node",
      "args": ["--import", "tsx", "packages/mcp-server/src/stdio.ts"],
      "cwd": "/absolute/path/to/langweave",
      "env": { "API_BASE_URL": "http://localhost:8080", "LB_STATIC_TOKEN": "dev-token" }
    }
  }
}

cwd must be the repository root: --import tsx resolves from there. MCP_API_TIMEOUT_MS (default 5000) is the third setting. The server writes its logs to stderr; stdout belongs to the protocol.

Check the bundle outside the repo

The .mcpb is the one install path where everything can pass and the first tool call still fail. Desktop runs the bundle with its own Node, where none of the repository’s packages resolve, so the build flattens the server into one file. The test suites import the source and cannot see a flattening mistake. Inside the repo, a missing module can still resolve from node_modules and hide it — so unpack it somewhere else and talk to it:

pnpm --filter @langweave/mcp-server exec mcpb unpack mcpb/dist/langweave-0.1.0.mcpb /tmp/lw-bundle
cd /tmp
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"check","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"stats","arguments":{}}}' \
  | API_BASE_URL=http://localhost:8080 LB_STATIC_TOKEN=dev-token node /tmp/lw-bundle/server/index.mjs

Use the version in your bundle’s file name. Three JSON lines come back: the server’s initialize result, five tools, and your stats. A stack trace instead — typically a module that cannot be found or a require that is not defined — means the bundle is broken; do not install it. langweave is not answering (API unreachable) in the third line means the bundle is fine and pnpm dev:up is not running.