Open WebUI: "Failed to connect to MCP server"

By MV2 of Munim, Inc., with AI agents. Written on 12 November 2026 from the source of Open WebUI v0.13.3 (the newest release that day), the MCP Python SDK (mcp) v2.3.0 that it bundles, and httpx2. Nothing was run; see limits.

You turn on an MCP tool server in a chat and get a red status line or toast:

Failed to connect to MCP server '<server id>'

The chat still answers, just without that server's tools. Open WebUI catches the error, shows this one message whatever went wrong, and moves on to the next tool (backend/open_webui/utils/middleware.py at v0.13.3: except Exception:, log.exception(...), then continue).

Short answer: the message names no cause, but the backend log does. At v0.13.3 the same text is logged at ERROR level with a traceback; the cause is the last line of that traceback. Run docker logs open-webui 2>&1 | grep -A40 "Failed to connect to MCP server" (use your container's name) and match the last line to the table below. The official MCP docs cover four causes (empty Bearer, function filter list, OAuth 2.1 default tools, slow handshake); this page adds the others we found in the code and the issue tracker.

If there is no traceback under the message, your build is older than PR #32229 (merged into dev on 11 October 2026). Before it, the reason was logged only at DEBUG level (#32213, reported on v0.11.x and v0.12.0). Set GLOBAL_LOG_LEVEL=DEBUG, reproduce once, then set it back.

The line under the error, and what it means

For Open WebUI 0.12.4 to 0.13.3, which bundle mcp==2.3.0 and httpx2==2.16.0. The texts in the first column are built by that code; the class name in front of them can differ in your traceback.

Last line of the tracebackCauseFix
Request 'initialize' timed out (or another method name in the quotes, such as 'tools/list')The server did not answer within MCP_INITIALIZE_TIMEOUT seconds (default 10). This timeout covers the handshake, listing tools and reading resources, not tool calls. Typical: cold starts, servers that build a big tool list on demand, a slow proxy. The SDK builds this text as f"Request {method!r} timed out" in mcp/shared/jsonrpc_dispatcher.py.Set MCP_INITIALIZE_TIMEOUT=60 (or what your server needs) on the Open WebUI container and restart it. Tool calls use AIOHTTP_CLIENT_TIMEOUT_TOOL_SERVER instead.
Redirect to https://… not followed; use that URL as the endpoint if it is the intended serverThe URL you entered answers with a redirect the SDK will not follow. See which redirects are followed: only 307 and 308, only to the same scheme, host and port, plus http:// to https:// on the default ports. A 301 or 302 is never followed, not even to the same host.Put the final URL from the message into the connection, including any trailing slash. There is no setting to follow other redirects (mcp v2.2.0 release notes).
Redirect to http://… not followed: it would downgrade this HTTPS endpoint to plain HTTP.The server sits behind a TLS-terminating proxy and doesn't know it, so its own redirects (often /mcp to /mcp/) point at http://.Use the exact https://…/ URL so no redirect happens, or make the server trust the proxy's forwarded headers (the SDK's transport docs give the same two fixes).
SSE stream failed: Server-sent event exceeded the 1048576 byte limit.One answer from the server, usually tools/list, is over 1 MiB. Open WebUI 0.12.4 to 0.13.3 has no setting for it (#34201, open).Expose fewer tools on the server. Details: MCP 1 MiB event limit.
Server returned an error responseThe server answered 4xx or 5xx without a JSON-RPC error body (mcp/client/streamable_http.py at v2.3.0, used for every status except 404). There is no separate text for 401, so a rejected or missing token looks like this. So can a POST to an endpoint that isn't Streamable HTTP (for example an old SSE-only URL ending in /sse). Look at the server's access log for the status code.401/403: check the auth type and token (below). 405 or 400: Open WebUI connects with Streamable HTTP only (streamable_http_client in utils/mcp/client.py), so point it at the server's Streamable HTTP endpoint (often /mcp), or put an SSE-only or stdio server behind a bridge such as mcpo and add it as an OpenAPI server instead.
Not FoundThe server answered 404 to the first request: the path is wrong. The SDK replaces a plain 404 with this text.Check the path (/mcp, /mcp/, or a prefix your proxy adds).
A ConnectError, such as All connection attempts failed or Name or service not knownOpen WebUI's backend can't reach the address at all. The usual case: the URL says localhost or 127.0.0.1, which inside the Open WebUI container is the container itself, not your machine. Your browser reaching the URL proves nothing, because the connection is made by the backend.Use http://host.docker.internal:<port>/mcp (Docker Desktop, or Linux with --add-host=host.docker.internal:host-gateway), or the service name if both run in one Compose project.
[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: …The server's certificate is self-signed or from a private CA. Open WebUI verifies it by default: AIOHTTP_CLIENT_SESSION_TOOL_SERVER_SSL defaults to True (env.py at v0.13.3).Set AIOHTTP_CLIENT_SESSION_TOOL_SERVER_SSL to the path of your CA bundle inside the container (the variable accepts true, false or a path). false also works but turns off certificate checks for these connections.
Illegal header value or 'ascii' codec can't encode character …, and only for some usersWith ENABLE_FORWARD_USER_INFO_HEADERS on (or a custom header that uses the user's name), the user's display name goes into a request header. A name with a leading or trailing space (#26181, closed 29 June 2026) or a non-ASCII letter such as Fábian (#29907, reported on v0.11.3, closed 17 September 2026) broke the request.Update. At v0.13.3 the forwarded name is trimmed and percent-encoded (quote(user.name.strip(), safe=' ') in utils/headers.py). We did not check names used in your own custom header templates.
Error getting OAuth token: … logged just before it, or No OAuth session found for user …An OAuth 2.1 server with no usable token for this user. Two known cases: the tool is a model default and the user never signed in to it (a known limitation per the docs, #20847), and, before v0.13.1, a 502/503 from the provider during token refresh deleted a valid session (#33803, fixed in v0.13.1 per its release notes).Enable the tool in the chat to sign in again; don't make OAuth 2.1 tools model defaults; update to v0.13.1 or later.

Which redirects are followed (Open WebUI 0.12.4 to 0.13.3)

Open WebUI leaves redirects to the SDK (create_httpx_client() at v0.13.3: "the MCP SDK follows same-origin redirects itself and ignores the client's follow_redirects setting"). In mcp 2.3.0, next_request_within_origin() in mcp/shared/_httpx_utils.py follows a redirect only if all three hold:

  1. The method stays the same. MCP requests are POSTs. httpx2 turns a POST into a GET on 301, 302 and 303 (_redirect_method(), the same rule httpx has always had), so those are refused. Only 307 and 308 keep the POST. This is why a reverse proxy rule like return 301 …/mcp/, or a redirect directive that defaults to 302, breaks the connection while a framework's own trailing-slash redirect (Starlette sends 307) works.
  2. The origin stays the same: same scheme, host and port. The one exception is http://host/ to https://host/ when both use the default port, so http://host:8000 to https://host:8443 is refused.
  3. No new user-info (user:pass@) appears in the target URL.

The rule came in mcp v2.2.0 (PR #3397; backported to v1.30.0 as PR #3448) because following redirects to another host sent the configured headers, and on 307/308 the request body, to that host. Open WebUI v0.12.3 bundled mcp 1.27.2, from before the change; we did not check how v0.12.3 itself handled redirects. Per python-sdk#3504 (open), people behind reverse proxies are asking for an opt-out; there is none in v2.3.0.

"Verify Connection" works, but chats fail

See what the server answers, from inside the container

This sends the same first request Open WebUI sends to a legacy server and prints the status, without following redirects. It uses only Python's standard library, which the Open WebUI image has. Replace the URL and add an Authorization header if your server needs one. We have not run this snippet.

docker exec -i open-webui python3 - <<'EOF'
import http.client, json, urllib.parse
url = "http://host.docker.internal:8000/mcp"   # the URL from the connection
u = urllib.parse.urlsplit(url)
C = http.client.HTTPSConnection if u.scheme == "https" else http.client.HTTPConnection
c = C(u.hostname, u.port, timeout=30)
body = json.dumps({"jsonrpc": "2.0", "id": 1, "method": "initialize",
                   "params": {"protocolVersion": "2025-06-18", "capabilities": {},
                              "clientInfo": {"name": "probe", "version": "0"}}})
c.request("POST", u.path or "/", body, {"Content-Type": "application/json",
                                        "Accept": "application/json, text/event-stream"})
r = c.getresponse()
print(r.status, r.reason, "| Location:", r.getheader("Location"),
      "| Content-Type:", r.getheader("Content-Type"))
EOF

200 with text/event-stream or application/json: the endpoint is fine and the cause is elsewhere (timeout, size, auth for real users). 301/302/303: change the URL to the Location shown. 307/308 to another host or port: same. 401/403: auth. 404/405: wrong path or not a Streamable HTTP endpoint. An exception instead of a status: network or TLS (the ConnectError and certificate rows of the table).

A different message: if tools worked at first and then a reply says MCP client is not connected. for every call, the server dropped the connection in the middle of that reply. Open WebUI v0.13.3 does not reconnect until the next message (#34170; fix proposed in PR #34174, open on 12 November 2026). With vLLM that reply can then end in "`tools` must not be an empty array".

How this was made, and its limits

AI agents working for MV2 of Munim, Inc. read these files on GitHub on 12 November 2026. Open WebUI v0.13.3: backend/open_webui/utils/middleware.py (the server:mcp: branch), utils/tools.py (build_tool_server_headers, connect_mcp_server), utils/headers.py, utils/mcp/client.py and env.py. MCP Python SDK v2.3.0: src/mcp/client/streamable_http.py, src/mcp/client/_probe.py, src/mcp/shared/_httpx_utils.py and src/mcp/shared/jsonrpc_dispatcher.py, plus the v2.2.0 and v1.30.0 release notes and the SDK's transport docs. httpx2: _redirect_method() in src/httpx2/httpx2/_client.py on its main branch, not at a tag. Nothing was run, including the snippet above. We followed the code paths by reading, not by tracing a real failure, so the exact traceback in your log may wrap these texts in another exception. The ConnectError and certificate texts are the usual Python and httpx wording, not read from httpx2's code. Facts from issues are marked with the issue. Open WebUI versions between 0.12.4 and 0.13.3 were not read one by one; the bundled package versions for 0.12.3, 0.12.4 and 0.13.3 come from their backend/requirements.txt. Corrections are welcome as issues at github.com/munimtechnologies/local-ai-checkup.

Check the rest of your setup

The free local-ai-checkup script shows which AI ports on your machine other computers can reach. The CVE checker tells you which security advisories affect your Open WebUI version. Both are read-only and send nothing off the machine.

Want someone to check it for you?

MV2 of Munim, Inc. does a $49 local AI health check for one machine, or a $199 small-office check for up to 5 machines or one shared Ollama, vLLM or Open WebUI server. You get a written report of what's exposed, risky or slow and what to fix first, with exact commands for your OS. See a sample report. Pay $49 or pay $199 on Stripe, then email mv2@munimtech.com the output of python3 local_ai_checkup.py --json, your OS, and what you use it for. MV2 never asks for passwords, keys or remote access.