Docs/AI Clients (MCP)

Standalone MCP server

Everything else in this section connects an AI client to a DBConvert Streams workspace — your saved connections, read through the app you already run. This page is the other shape: the same read-only server, given connection strings directly, with no DBConvert Streams installation behind it. No workspace database, no keyring, no services to start.

It is the same binary and the same tools. What changes is where the sources come from: instead of reading your workspace, the server serves exactly the sources you hand it at startup.

What counts as a source

Four kinds, and they mix freely:

postgres://user:password@host:5432/dbname
mysql://user:password@host:3306/dbname
s3://bucket/folder?region=us-east-1
/home/you/data                          # a folder of Parquet, CSV or JSON files

Put a name in front to choose what the source is called in chat — shop=postgres://…. Without one it takes the name of the database, bucket or folder it points at.

The point of listing several is that one question can join across them: a live PostgreSQL table against a Parquet file in S3, or a CSV a colleague sent against the table it was exported from. See federated validation for a worked example.

Option 1 — the Claude extension

Download dbconvert-streams-<version>.mcpb from Releases and drop it into Claude → Settings → Extensions. Fill in the form and the tools appear in your next chat.

One file covers Windows and Linux — the bundle carries a binary for each and picks the right one on install. macOS is planned for a later release.

Two fields matter:

  • Connection strings — several in the one field, separated by spaces. The form renders it as a single input, so this is the only way to give it more than one: 
    shop=postgres://user:password@host:5432/shop orders=mysql://user:password@host:3306/orders
  • Folders with data files — use + Add directory. A folder path may contain spaces; it is picked, not typed, so nothing is ambiguous.

The two AWS fields matter only for an S3 source on storage that is not AWS itself — MinIO, Cloudflare R2, DigitalOcean Spaces.

Option 2 — the Docker image

Any MCP client that can launch a server through Docker can run this, which is most of them:

docker run -i --rm slotix/stream-mcp postgres://user:password@host:5432/dbname

-i is required: MCP speaks JSON-RPC over standard input, so the container needs its stdin held open. --rm is housekeeping — the server keeps no state between runs.

Several sources are several arguments:

docker run -i --rm slotix/stream-mcp \
  shop=postgres://user:password@host:5432/shop \
  orders=mysql://user:password@host:3306/orders \
  lake=s3://analytics/exports?region=eu-central-1

A folder has to be mounted before it can be read, and the path you pass is the path inside the container:

docker run -i --rm -v /home/you/data:/data slotix/stream-mcp /data

S3 credentials come from the standard AWS variables, never from the URL, so they stay out of your shell history and out of the client's config file:

docker run -i --rm \
  -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY \
  slotix/stream-mcp "s3://analytics/exports?region=eu-central-1"

Reaching a database on your own machine

A container has its own network. localhost inside it means the container, not your computer, so a database running on the host needs one of:

  • --network host on Linux, then 127.0.0.1 works as usual;
  • host.docker.internal as the host name on macOS and Windows Docker Desktop.

A database on another server needs neither — use its address as you normally would.

Registering it with a client

In a client's MCP configuration the same command becomes:

{
  "mcpServers": {
    "dbconvert": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "slotix/stream-mcp",
               "shop=postgres://user:password@host:5432/shop"]
    }
  }
}

The server is listed in the MCP registry as com.dbconvert/streams, with both the extension and the image, so clients that install from the registry can find it without this file.

What you get, and what you don't

The tool surface follows the sources you configured. A server started with only a folder gets the file and federated tools; add a database and the catalog, inspection and query tools appear; add a bucket and the object-storage tools join them. Nothing needs enabling — an unconfigured server simply starts with an empty source list and says so.

What is not there, compared with a workspace-backed server: the stream tools. Stream status, run errors and stream logs describe a DBConvert Streams installation, and in standalone mode there isn't one.

Everything the read-only guarantee covers still holds — see Safety & privacy. There is no tool that writes, and connection details are given once, at startup, so they never travel through a tool call into the conversation or the chat history.

One honest caveat about the command line: arguments to a process are visible to other processes on the same machine (ps, or docker inspect for a container). On a personal machine that is your own account's processes and nobody else's; on a shared host, prefer the extension, which stores the value in the client's own configuration rather than an argument list you type into a shell.

Logging

The server refuses to start without a log destination, because standard output carries the protocol and a stray log line would corrupt it. The extension supplies one from its manifest, and the Docker image has its own inside the container. Running the binary directly, set LOG_FILE yourself:

LOG_FILE=~/.dbconvert-streams/stream-mcp.log stream-mcp postgres://…

Inside a container that log is written to /app/logs, which --rm throws away with the container. Mount the folder to keep it:

docker run -i --rm -v ./logs:/app/logs slotix/stream-mcp postgres://…

Writes are buffered and flushed once a second, so a server that is killed in its first second leaves nothing behind — worth knowing before concluding that a crashing container logs nothing.

PreviousSetupNextSafety & Privacy