MCP troubleshooting

Find your symptom below, then check the FAQ. If you're still wiring things up, see Setup; for what the server can and cannot do, see Safety & privacy.

First: where your files actually live

When you set up through the ✨ AI Assistants panel in the desktop app, your config database and logs live in a platform-specific folder:

The shell examples below use $DBC for that folder — set it once from your row so you can paste them directly:

export DBC=~/.local/share/dbconvert-streams   # adjust to your platform

Not sure it's the right folder? The one that contains a recently-modified config.db is the live one. The MCP server writes its log (stream-mcp.log) next to that config.db, in the config/ subfolder.

Running in Docker? The config DB and logs live inside the container, not on the host — the file paths and shell commands on this page don't apply. Inspect the MCP service with docker logs / docker exec, and connect your client over the HTTP transport.

"Failed to connect" or server shows a red status

The MCP server is registered but your AI client can't talk to it.

• Desktop (panel): open the client's card, read the Last action output for the actual error, then Disconnect → Connect again and restart the client. The panel wires the binary path, workspace identity, and master key for you, so a failure here is usually a stale client that just needs the restart.
• Docker (HTTP): confirm the endpoint is reachable (http(s)://<host>/mcp), the API key and Install ID are correct, and — on HTTPS with a self-signed certificate — that your client trusts it. nginx must route /mcp to the MCP service.

Missing master key

Common error:

master key is required (set SECRETS_MASTER_KEY)

The MCP server can't read your encrypted secrets file without the master key.

• Desktop: the key lives in your OS keyring and is read automatically — you never type it. If you hit this after a panel install, the keyring entry is missing or unreadable; Disconnect → Connect from the panel to re-resolve it.
• Docker / self-hosted server: there may be no OS keyring. Set SECRETS_MASTER_KEY (in the deployment's environment or .env) to the same value your DBConvert Streams API uses.

The AI ignores the tools and greps files instead (Codex CLI)

Codex's coding harness biases small prompts toward repository exploration: ask it to "show db connections" and it may search your project for config files instead of calling MCP. Two fixes:

• Name the product in the request the first time: "show connections from dbconvert streams" — once it has called a tool, it keeps using them for the rest of the session.
• Or make it permanent: add a line to the AGENTS.md in your working directory — "For anything about database connections, schemas, or streams, use the dbconvert-streams MCP tools, not shell commands."

Other clients (Cursor, Claude Code, Claude Desktop, VS Code Copilot, Windsurf, Gemini CLI) route to the tools without prompting hints.

"Connection not found" but the UI shows it

The MCP server is reading a different config database than the app is writing to. List who owns which connections in the one you expect:

sqlite3 $DBC/config/config.db \
  "SELECT user_id, COUNT(*) FROM connections GROUP BY user_id;"

If the connection you're missing isn't there, the server is on the wrong workspace. From the panel: Disconnect, then Connect again — it always targets the workspace Data Explorer uses — and restart the client.

"Connection list is stale" — AI sees old names after you renamed something

The MCP server normally picks up changes within ~200 ms via filesystem watching. If it does not:

• Check that the config database's WAL file was modified after your save:

  stat $DBC/config/config.db-wal
  

• As a last resort, restart your AI client so a fresh MCP server spawns

The AI says a table is empty when it isn't

The assistant reports no rows even though you know there's data. It's almost always looking in the wrong place — tell it where:

• Wrong database. One connection can hold several databases. Ask the AI to list the databases on this connection first, then name the right one — e.g. "query orders in the sales database."
• Wrong schema. In PostgreSQL public isn't always the only schema. Ask it to list the schemas first, or name the schema explicitly — e.g. "look in the analytics schema."

Query timed out

The MCP server enforces a 10-second default timeout (60 seconds maximum if the AI passes timeoutSeconds). Queries that hit the timeout return an error to the AI, which can then narrow the query with LIMIT / WHERE clauses or split it into steps.

If you want a longer ceiling for an unusual investigation, ask the AI to "use the maximum allowed timeout of 60 seconds" — it will set timeoutSeconds: 60 on the next call.

Response truncated even on small queries

The MCP server caps responses at 256 KB (soft) and 1 MB (hard). If you see truncated: true on a small-looking result, it usually means the rows contain long TEXT / JSON / BLOB columns whose total size exceeds the cap.

Workarounds:

• Ask the AI to SELECT only the columns you actually need rather than SELECT *
• Reduce the row limit
• Filter to narrower date / ID ranges

Logs

The MCP server writes its activity log to config/stream-mcp.log — next to the config database. Useful filters:

# Every tool call with duration
grep "mcp tool call" $DBC/config/stream-mcp.log | tail -50

# Only failures
grep "mcp tool call failed" $DBC/config/stream-mcp.log

Your AI client may also keep its own MCP I/O log:

• Claude Code: ~/.cache/claude-cli-nodejs/<project>/mcp-logs-dbconvert-streams/*.jsonl
• Claude Desktop: ~/Library/Logs/Claude/mcp*.log (macOS), ~/.config/Claude/logs/mcp*.log (Linux), or %APPDATA%\Claude\logs\mcp*.log (Windows)
• Cursor: Output panel → MCP channel
• VS Code Copilot: Output panel → "MCP: dbconvert-streams" channel
• Codex CLI: ~/.codex/log/ (e.g. codex-tui.log)

Windows note. The sqlite3, stat, and grep commands on this page assume a Unix shell. On Windows use WSL, Git Bash, or the equivalent PowerShell cmdlets (Get-Item, Select-String), and read config.db with any SQLite client. The MCP server log is plain text next to config.db in the config/ folder of your app data directory (see the table at the top of this page).

FAQ

I clicked Disconnect but /mcp still shows dbconvert-streams connected

Restart the AI client. Disconnect removes the registration from the client's config, but a client that's already running keeps the MCP server process it spawned at startup — so in the same session it still lists the tools. After a restart the client re-reads its config, finds no entry, and drops it. (Connecting needs a restart for the same reason.)

Can multiple AI clients use the MCP server at the same time?

Yes. Each AI client spawns its own MCP server child process. They all read from the same config database and do not interfere with each other.

Does the AI use my paid model tokens?

Yes. Each tool call sends the tool name, parameters, and result through your AI provider. Large responses consume more tokens. The 256 KB soft cap helps — if the AI's query would return more, the server truncates and tells the AI to narrow the request.

Can I limit which tools the AI uses?

Yes — most clients have per-tool toggles, Claude Code uses permission rules, and the strongest limit is a read-only database user. The per-client steps are in Keeping data from the AI provider.

Can the AI accidentally delete or modify data?

No. The MCP server rejects any non-SELECT SQL at the application layer, has no tools that mutate state, and (recommended) you can layer a read-only database user underneath as defense in depth. The AI suggests changes; you execute them.

What happens to my data?

It depends entirely on your AI client and provider. The MCP server runs on your own infrastructure (your machine for stdio, your Docker host for HTTP) and never sends data anywhere on its own — but whatever the AI sees, the AI provider sees. See What goes to your AI provider for the full picture.

Can I add my own custom tools to the MCP server?

Not currently. The 26 tools are fixed for the current release. Custom extensions are a possible future direction.

Does it work in Docker / Kubernetes deployments?

Yes — over the HTTP transport, whether the container runs on your own machine or a remote server/cluster. A Docker deployment already runs stream-mcp as a service behind nginx, so your AI client connects to http(s)://<host>/mcp with your API key — nothing to install on the host (http://localhost/mcp for a local stack). stdio, where the client launches the binary locally, is the desktop-app path. See Setup → Connect a remote AI client.