Connect an agent

Your agent talks to BasaltDB over MCP. Its MCP client starts basalt mcp --agent NAME, a small program that relays to the engine for that agent. It holds no credential. The engine checks that the program is run by the agent’s OS user and refuses anyone else.

Before you start, run basalt init --agent NAME for the agent. See Install, or the Quickstart for the sample agent demo_bot. The examples below use demo_bot.

What every client needs

Any MCP client takes a command and its arguments. Add one server per agent.

{
  "mcpServers": {
    "basalt-demo_bot": {
      "command": "/usr/local/bin/basalt",
      "args": ["mcp", "--agent", "demo_bot"]
    }
  }
}

• Use the absolute path of basalt (which basalt) if the client does not inherit your PATH.
• If init used a non-default --socket-dir, add "--socket-dir", "DIR" to args.
• Do not put a database URL in the client config. The agent never holds one.

OpenCode

Add the server to opencode.json in your project, or to ~/.config/opencode/opencode.json to use it everywhere.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "basalt-demo_bot": {
      "type": "local",
      "command": ["/usr/local/bin/basalt", "mcp", "--agent", "demo_bot"],
      "enabled": true
    }
  }
}

Start opencode and ask it which basalt tools it has. It should list run_start, query and write, among others.

Claude Code

claude mcp add basalt-demo_bot -- "$(which basalt)" mcp --agent demo_bot

If the claude command was on your PATH, basalt init offered to run this and may have done it already. It adds the server for sessions started in the current directory. Add --scope user to use it from any directory.

Start claude and run /mcp. basalt-demo_bot should show as connected with its tools.

Codex

codex mcp add basalt-demo_bot -- "$(which basalt)" mcp --agent demo_bot

Or add it to ~/.codex/config.toml yourself:

[mcp_servers.basalt-demo_bot]
command = "/usr/local/bin/basalt"
args = ["mcp", "--agent", "demo_bot"]

Start codex and ask it which basalt tools it has.

A bot on its own computer

Your bot runs on a machine you cannot reach, such as a server or a chat bot’s host. The bot installs the engine there. You approve it from your own computer, where your database password stays. The bot never sees the admin connection string.

On the bot’s machine, with basalt installed there (see Install), the bot runs basalt init --remote. It needs the connection string without a password. Supabase shows it with a [YOUR-PASSWORD] placeholder.

basalt init --remote --agent my_bot --operated-by=agent \
  --write public.leads --read public.lead_notes \
  --database-url "postgresql://postgres@HOST:5432/postgres"

It prints a setup code and a fingerprint, such as 3f9a 21c0 7d44 e1b2 90ac. The code is valid for 24 hours and works once. The bot shows both in the chat.

On your own computer, with the admin connection string at the hidden prompt:

basalt init --setup-code SETUP_CODE

Check that the fingerprint it shows matches the one your bot gave you. If it does not, stop and ask your bot for a new code. Then read what the setup will do, answer y, and register a passkey when it asks. It ends with Done. Tell my_bot to check its status.

basalt init --remote does not install or start the engine. Your bot does that on its own machine, by running basalt engine --config PATH, or by installing it as a service. When the engine sees that your setup ran, it starts serving the agent.

Tell the bot. It calls its status tool and confirms it is ready.

Never paste your database password into the chat. The setup code holds no secret. For the full walkthrough and what each step checks, see A bot on its own computer.

Check that it works

Run this on the machine where the agent runs. It sends one MCP initialize request through the relay.

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"check","version":"0"}}}' \
  | basalt mcp --agent demo_bot

A JSON response naming the server basalt means the relay reached the engine. If the connection closes at once, the engine refused the program: run the command as the agent’s OS user, or check osUser in the engine config. basalt status --agent demo_bot prints the engine, the guard and the passkey, with the fix for each problem.

What your agent can call

The client lists BasaltDB’s tools: run_start, describe, query, write, run_history, list_runs, list_pending, preview_revert, request_revert and status, plus revert_plan and apply_revert_batch for large undos. A session usually starts a run with a reason, reads with query inside that run, and writes with write and a reason. See MCP tools.