[{"data":1,"prerenderedAt":765},["ShallowReactive",2],{"docs-\u002Fdocs\u002Fmcp\u002Ftroubleshooting":3},{"id":4,"title":5,"body":6,"description":756,"extension":757,"meta":758,"navigation":759,"path":760,"redirect":761,"seo":762,"stem":763,"__hash__":764},"docs\u002Fdocs\u002Fmcp\u002Ftroubleshooting.md","MCP troubleshooting",{"type":7,"value":8,"toc":732},"minimark",[9,13,33,38,46,97,104,136,154,179,183,186,218,223,226,234,237,262,266,269,289,292,296,299,327,338,342,345,368,372,375,413,417,431,438,442,459,462,480,484,491,549,552,605,637,640,647,650,654,657,661,664,668,675,679,685,689,697,701,704,708,728],[10,11,5],"h1",{"id":12},"mcp-troubleshooting",[14,15,16,17,22,23,27,28,32],"p",{},"Find your symptom below, then check the ",[18,19,21],"a",{"href":20},"#faq","FAQ",". If you're still wiring things up, see ",[18,24,26],{"href":25},"\u002Fdocs\u002Fmcp\u002Fsetup","Setup","; for what the server can and cannot do, see ",[18,29,31],{"href":30},"\u002Fdocs\u002Fmcp\u002Fsafety-and-privacy","Safety & privacy",".",[34,35,37],"h2",{"id":36},"first-where-your-files-actually-live","First: where your files actually live",[14,39,40,41,45],{},"When you set up through the ✨ AI Assistants panel in the desktop app, your config database and logs live in a ",[42,43,44],"strong",{},"platform-specific folder",":",[47,48,49,62],"table",{},[50,51,52],"thead",{},[53,54,55,59],"tr",{},[56,57,58],"th",{},"Platform",[56,60,61],{},"Config dir",[63,64,65,77,87],"tbody",{},[53,66,67,71],{},[68,69,70],"td",{},"Linux",[68,72,73],{},[74,75,76],"code",{},"~\u002F.local\u002Fshare\u002Fdbconvert-streams\u002F",[53,78,79,82],{},[68,80,81],{},"macOS",[68,83,84],{},[74,85,86],{},"~\u002FLibrary\u002FApplication Support\u002FDBConvert Streams\u002F",[53,88,89,92],{},[68,90,91],{},"Windows",[68,93,94],{},[74,95,96],{},"%APPDATA%\\DBConvert Streams\\",[14,98,99,100,103],{},"The shell examples below use ",[74,101,102],{},"$DBC"," for that folder — set it once from your row so you can paste them directly:",[105,106,111],"pre",{"className":107,"code":108,"language":109,"meta":110,"style":110},"language-bash shiki shiki-themes github-light github-dark","export DBC=~\u002F.local\u002Fshare\u002Fdbconvert-streams   # adjust to your platform\n","bash","",[74,112,113],{"__ignoreMap":110},[114,115,118,122,126,129,132],"span",{"class":116,"line":117},"line",1,[114,119,121],{"class":120},"szBVR","export",[114,123,125],{"class":124},"sVt8B"," DBC",[114,127,128],{"class":120},"=~",[114,130,131],{"class":124},"\u002F.local\u002Fshare\u002Fdbconvert-streams   ",[114,133,135],{"class":134},"sJ8bj","# adjust to your platform\n",[14,137,138,139,142,143,146,147,149,150,153],{},"Not sure it's the right folder? The one that contains a recently-modified ",[74,140,141],{},"config.db"," is the live one. The MCP server writes its log (",[74,144,145],{},"stream-mcp.log",") next to that ",[74,148,141],{},", in the ",[74,151,152],{},"config\u002F"," subfolder.",[155,156,157],"blockquote",{},[14,158,159,162,163,166,167,170,171,174,175,32],{},[42,160,161],{},"Running in Docker?"," The config DB and logs live ",[42,164,165],{},"inside the container",", not on the host — the file paths and shell commands on this page don't apply. Inspect the MCP service with ",[74,168,169],{},"docker logs"," \u002F ",[74,172,173],{},"docker exec",", and connect your client over the ",[18,176,178],{"href":177},"\u002Fdocs\u002Fmcp\u002Fsetup#connect-a-remote-ai-client-http","HTTP transport",[34,180,182],{"id":181},"failed-to-connect-or-server-shows-a-red-status","\"Failed to connect\" or server shows a red status",[14,184,185],{},"The MCP server is registered but your AI client can't talk to it.",[187,188,189,204],"ul",{},[190,191,192,195,196,199,200,203],"li",{},[42,193,194],{},"Desktop (panel):"," open the client's card, read the ",[42,197,198],{},"Last action output"," for the actual error, then ",[42,201,202],{},"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.",[190,205,206,209,210,213,214,217],{},[42,207,208],{},"Docker (HTTP):"," confirm the endpoint is reachable (",[74,211,212],{},"http(s):\u002F\u002F\u003Chost>\u002Fmcp","), the API key and Install ID are correct, and — on HTTPS with a self-signed certificate — that your client trusts it. nginx must route ",[74,215,216],{},"\u002Fmcp"," to the MCP service.",[219,220,222],"h3",{"id":221},"missing-master-key","Missing master key",[14,224,225],{},"Common error:",[105,227,232],{"className":228,"code":230,"language":231},[229],"language-text","master key is required (set SECRETS_MASTER_KEY)\n","text",[74,233,230],{"__ignoreMap":110},[14,235,236],{},"The MCP server can't read your encrypted secrets file without the master key.",[187,238,239,248],{},[190,240,241,244,245,247],{},[42,242,243],{},"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; ",[42,246,202],{}," from the panel to re-resolve it.",[190,249,250,253,254,257,258,261],{},[42,251,252],{},"Docker \u002F self-hosted server:"," there may be no OS keyring. Set ",[74,255,256],{},"SECRETS_MASTER_KEY"," (in the deployment's environment or ",[74,259,260],{},".env",") to the same value your DBConvert Streams API uses.",[34,263,265],{"id":264},"the-ai-ignores-the-tools-and-greps-files-instead-codex-cli","The AI ignores the tools and greps files instead (Codex CLI)",[14,267,268],{},"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:",[187,270,271,279],{},[190,272,273,274,278],{},"Name the product in the request the first time: ",[275,276,277],"em",{},"\"show connections from dbconvert streams\""," — once it has called a tool, it keeps using them for the rest of the session.",[190,280,281,282,285,286],{},"Or make it permanent: add a line to the ",[74,283,284],{},"AGENTS.md"," in your working directory — ",[275,287,288],{},"\"For anything about database connections, schemas, or streams, use the dbconvert-streams MCP tools, not shell commands.\"",[14,290,291],{},"Other clients (Cursor, Claude Code, Claude Desktop, VS Code Copilot, Windsurf, Gemini CLI) route to the tools without prompting hints.",[34,293,295],{"id":294},"connection-not-found-but-the-ui-shows-it","\"Connection not found\" but the UI shows it",[14,297,298],{},"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:",[105,300,302],{"className":107,"code":301,"language":109,"meta":110,"style":110},"sqlite3 $DBC\u002Fconfig\u002Fconfig.db \\\n  \"SELECT user_id, COUNT(*) FROM connections GROUP BY user_id;\"\n",[74,303,304,321],{"__ignoreMap":110},[114,305,306,310,313,317],{"class":116,"line":117},[114,307,309],{"class":308},"sScJk","sqlite3",[114,311,312],{"class":124}," $DBC",[114,314,316],{"class":315},"sZZnC","\u002Fconfig\u002Fconfig.db",[114,318,320],{"class":319},"sj4cs"," \\\n",[114,322,324],{"class":116,"line":323},2,[114,325,326],{"class":315},"  \"SELECT user_id, COUNT(*) FROM connections GROUP BY user_id;\"\n",[14,328,329,330,333,334,337],{},"If the connection you're missing isn't there, the server is on the wrong workspace. From the panel: ",[42,331,332],{},"Disconnect",", then ",[42,335,336],{},"Connect"," again — it always targets the workspace Data Explorer uses — and restart the client.",[34,339,341],{"id":340},"connection-list-is-stale-ai-sees-old-names-after-you-renamed-something","\"Connection list is stale\" — AI sees old names after you renamed something",[14,343,344],{},"The MCP server normally picks up changes within ~200 ms via filesystem watching. If it does not:",[187,346,347,365],{},[190,348,349,350],{},"Check that the config database's WAL file was modified after your save:\n",[105,351,353],{"className":107,"code":352,"language":109,"meta":110,"style":110},"stat $DBC\u002Fconfig\u002Fconfig.db-wal\n",[74,354,355],{"__ignoreMap":110},[114,356,357,360,362],{"class":116,"line":117},[114,358,359],{"class":319},"stat",[114,361,312],{"class":124},[114,363,364],{"class":315},"\u002Fconfig\u002Fconfig.db-wal\n",[190,366,367],{},"As a last resort, restart your AI client so a fresh MCP server spawns",[34,369,371],{"id":370},"the-ai-says-a-table-is-empty-when-it-isnt","The AI says a table is empty when it isn't",[14,373,374],{},"The assistant reports no rows even though you know there's data. It's almost always looking in the wrong place — tell it where:",[187,376,377,395],{},[190,378,379,382,383,386,387,390,391,394],{},[42,380,381],{},"Wrong database."," One connection can hold several databases. Ask the AI to ",[275,384,385],{},"list the databases on this connection"," first, then name the right one — e.g. \"query ",[74,388,389],{},"orders"," in the ",[74,392,393],{},"sales"," database.\"",[190,396,397,400,401,404,405,408,409,412],{},[42,398,399],{},"Wrong schema."," In PostgreSQL ",[74,402,403],{},"public"," isn't always the only schema. Ask it to ",[275,406,407],{},"list the schemas"," first, or name the schema explicitly — e.g. \"look in the ",[74,410,411],{},"analytics"," schema.\"",[34,414,416],{"id":415},"query-timed-out","Query timed out",[14,418,419,420,423,424,170,427,430],{},"The MCP server enforces a 10-second default timeout (60 seconds maximum if the AI passes ",[74,421,422],{},"timeoutSeconds","). Queries that hit the timeout return an error to the AI, which can then narrow the query with ",[74,425,426],{},"LIMIT",[74,428,429],{},"WHERE"," clauses or split it into steps.",[14,432,433,434,437],{},"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 ",[74,435,436],{},"timeoutSeconds: 60"," on the next call.",[34,439,441],{"id":440},"response-truncated-even-on-small-queries","Response truncated even on small queries",[14,443,444,445,448,449,170,452,170,455,458],{},"The MCP server caps responses at 256 KB (soft) and 1 MB (hard). If you see ",[74,446,447],{},"truncated: true"," on a small-looking result, it usually means the rows contain long ",[74,450,451],{},"TEXT",[74,453,454],{},"JSON",[74,456,457],{},"BLOB"," columns whose total size exceeds the cap.",[14,460,461],{},"Workarounds:",[187,463,464,474,477],{},[190,465,466,467,470,471],{},"Ask the AI to ",[74,468,469],{},"SELECT"," only the columns you actually need rather than ",[74,472,473],{},"SELECT *",[190,475,476],{},"Reduce the row limit",[190,478,479],{},"Filter to narrower date \u002F ID ranges",[34,481,483],{"id":482},"logs","Logs",[14,485,486,487,490],{},"The MCP server writes its activity log to ",[74,488,489],{},"config\u002Fstream-mcp.log"," — next to the config database. Useful filters:",[105,492,494],{"className":107,"code":493,"language":109,"meta":110,"style":110},"# Every tool call with duration\ngrep \"mcp tool call\" $DBC\u002Fconfig\u002Fstream-mcp.log | tail -50\n\n# Only failures\ngrep \"mcp tool call failed\" $DBC\u002Fconfig\u002Fstream-mcp.log\n",[74,495,496,501,523,530,536],{"__ignoreMap":110},[114,497,498],{"class":116,"line":117},[114,499,500],{"class":134},"# Every tool call with duration\n",[114,502,503,506,509,511,514,517,520],{"class":116,"line":323},[114,504,505],{"class":308},"grep",[114,507,508],{"class":315}," \"mcp tool call\"",[114,510,312],{"class":124},[114,512,513],{"class":315},"\u002Fconfig\u002Fstream-mcp.log",[114,515,516],{"class":120}," |",[114,518,519],{"class":308}," tail",[114,521,522],{"class":319}," -50\n",[114,524,526],{"class":116,"line":525},3,[114,527,529],{"emptyLinePlaceholder":528},true,"\n",[114,531,533],{"class":116,"line":532},4,[114,534,535],{"class":134},"# Only failures\n",[114,537,539,541,544,546],{"class":116,"line":538},5,[114,540,505],{"class":308},[114,542,543],{"class":315}," \"mcp tool call failed\"",[114,545,312],{"class":124},[114,547,548],{"class":315},"\u002Fconfig\u002Fstream-mcp.log\n",[14,550,551],{},"Your AI client may also keep its own MCP I\u002FO log:",[187,553,554,563,580,586,592],{},[190,555,556,559,560],{},[42,557,558],{},"Claude Code",": ",[74,561,562],{},"~\u002F.cache\u002Fclaude-cli-nodejs\u002F\u003Cproject>\u002Fmcp-logs-dbconvert-streams\u002F*.jsonl",[190,564,565,559,568,571,572,575,576,579],{},[42,566,567],{},"Claude Desktop",[74,569,570],{},"~\u002FLibrary\u002FLogs\u002FClaude\u002Fmcp*.log"," (macOS), ",[74,573,574],{},"~\u002F.config\u002FClaude\u002Flogs\u002Fmcp*.log"," (Linux), or ",[74,577,578],{},"%APPDATA%\\Claude\\logs\\mcp*.log"," (Windows)",[190,581,582,585],{},[42,583,584],{},"Cursor",": Output panel → MCP channel",[190,587,588,591],{},[42,589,590],{},"VS Code Copilot",": Output panel → \"MCP: dbconvert-streams\" channel",[190,593,594,559,597,600,601,604],{},[42,595,596],{},"Codex CLI",[74,598,599],{},"~\u002F.codex\u002Flog\u002F"," (e.g. ",[74,602,603],{},"codex-tui.log",")",[155,606,607],{},[14,608,609,612,613,615,616,618,619,621,622,615,625,628,629,631,632,390,634,636],{},[42,610,611],{},"Windows note."," The ",[74,614,309],{},", ",[74,617,359],{},", and ",[74,620,505],{}," commands on this page assume a Unix shell. On Windows use WSL, Git Bash, or the equivalent PowerShell cmdlets (",[74,623,624],{},"Get-Item",[74,626,627],{},"Select-String","), and read ",[74,630,141],{}," with any SQLite client. The MCP server log is plain text next to ",[74,633,141],{},[74,635,152],{}," folder of your app data directory (see the table at the top of this page).",[34,638,21],{"id":639},"faq",[219,641,643,644,646],{"id":642},"i-clicked-disconnect-but-mcp-still-shows-dbconvert-streams-connected","I clicked Disconnect but ",[74,645,216],{}," still shows dbconvert-streams connected",[14,648,649],{},"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.)",[219,651,653],{"id":652},"can-multiple-ai-clients-use-the-mcp-server-at-the-same-time","Can multiple AI clients use the MCP server at the same time?",[14,655,656],{},"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.",[219,658,660],{"id":659},"does-the-ai-use-my-paid-model-tokens","Does the AI use my paid model tokens?",[14,662,663],{},"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.",[219,665,667],{"id":666},"can-i-limit-which-tools-the-ai-uses","Can I limit which tools the AI uses?",[14,669,670,671,32],{},"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 ",[18,672,674],{"href":673},"\u002Fdocs\u002Fmcp\u002Fsafety-and-privacy#keeping-data-from-the-ai-provider","Keeping data from the AI provider",[219,676,678],{"id":677},"can-the-ai-accidentally-delete-or-modify-data","Can the AI accidentally delete or modify data?",[14,680,681,682,684],{},"No. The MCP server rejects any non-",[74,683,469],{}," 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.",[219,686,688],{"id":687},"what-happens-to-my-data","What happens to my data?",[14,690,691,692,696],{},"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 ",[18,693,695],{"href":694},"\u002Fdocs\u002Fmcp\u002Fsafety-and-privacy#what-goes-to-your-ai-provider","What goes to your AI provider"," for the full picture.",[219,698,700],{"id":699},"can-i-add-my-own-custom-tools-to-the-mcp-server","Can I add my own custom tools to the MCP server?",[14,702,703],{},"Not currently. The 26 tools are fixed for the current release. Custom extensions are a possible future direction.",[219,705,707],{"id":706},"does-it-work-in-docker-kubernetes-deployments","Does it work in Docker \u002F Kubernetes deployments?",[14,709,710,711,713,714,717,718,720,721,724,725,32],{},"Yes — over the ",[42,712,178],{},", whether the container runs on your own machine or a remote server\u002Fcluster. A Docker deployment already runs ",[74,715,716],{},"stream-mcp"," as a service behind nginx, so your AI client connects to ",[74,719,212],{}," with your API key — nothing to install on the host (",[74,722,723],{},"http:\u002F\u002Flocalhost\u002Fmcp"," for a local stack). stdio, where the client launches the binary locally, is the desktop-app path. See ",[18,726,727],{"href":177},"Setup → Connect a remote AI client",[729,730,731],"style",{},"html pre.shiki code .szBVR, html code.shiki .szBVR{--shiki-default:#D73A49;--shiki-dark:#F97583}html pre.shiki code .sVt8B, html code.shiki .sVt8B{--shiki-default:#24292E;--shiki-dark:#E1E4E8}html pre.shiki code .sJ8bj, html code.shiki .sJ8bj{--shiki-default:#6A737D;--shiki-dark:#6A737D}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .sScJk, html code.shiki .sScJk{--shiki-default:#6F42C1;--shiki-dark:#B392F0}html pre.shiki code .sZZnC, html code.shiki .sZZnC{--shiki-default:#032F62;--shiki-dark:#9ECBFF}html pre.shiki code .sj4cs, html code.shiki .sj4cs{--shiki-default:#005CC5;--shiki-dark:#79B8FF}",{"title":110,"searchDepth":323,"depth":323,"links":733},[734,735,738,739,740,741,742,743,744,745],{"id":36,"depth":323,"text":37},{"id":181,"depth":323,"text":182,"children":736},[737],{"id":221,"depth":525,"text":222},{"id":264,"depth":323,"text":265},{"id":294,"depth":323,"text":295},{"id":340,"depth":323,"text":341},{"id":370,"depth":323,"text":371},{"id":415,"depth":323,"text":416},{"id":440,"depth":323,"text":441},{"id":482,"depth":323,"text":483},{"id":639,"depth":323,"text":21,"children":746},[747,749,750,751,752,753,754,755],{"id":642,"depth":525,"text":748},"I clicked Disconnect but \u002Fmcp still shows dbconvert-streams connected",{"id":652,"depth":525,"text":653},{"id":659,"depth":525,"text":660},{"id":666,"depth":525,"text":667},{"id":677,"depth":525,"text":678},{"id":687,"depth":525,"text":688},{"id":699,"depth":525,"text":700},{"id":706,"depth":525,"text":707},"Fixes for common DBConvert Streams MCP setup and runtime issues, plus an FAQ.","md",{},false,"\u002Fdocs\u002Fmcp\u002Ftroubleshooting",null,{"title":5,"description":756},"docs\u002Fmcp\u002Ftroubleshooting","cxj39jK6KEtn2GGEB2o6cKAxvmLaMSd43QeCMZ3Sa4Q",1781271517539]