doc: add MCP troubleshooting guide

docs/my-website/docs/mcp.md

@@ -60,6 +60,8 @@ model_list:
 
 If `supported_db_objects` is not set, all object types are loaded from the database (default behavior).
 
+For diagnosing connectivity problems after setup, see the [MCP Troubleshooting Guide](./mcp_troubleshoot.md).
+
 <Tabs>
 <TabItem value="ui" label="LiteLLM UI">
 
@@ -1484,3 +1486,7 @@ At the moment LiteLLM only forwards whatever `Authorization` header/value you co
 **Q: When I fetch an OAuth token from the LiteLLM UI, where is it stored?**
 
 The UI keeps only transient state in `sessionStorage` so the OAuth redirect flow can finish; the token is not persisted in the server or database.
+
+**Q: I'm seeing MCP connection errors—what should I check?**
+
+Walk through the [MCP Troubleshooting Guide](./mcp_troubleshoot.md) for step-by-step isolation (Client → LiteLLM vs. LiteLLM → MCP), log examples, and verification methods like MCP Inspector and `curl`.

docs/my-website/docs/mcp_troubleshoot.md

@@ -0,0 +1,99 @@
+import Image from '@theme/IdealImage';
+
+# MCP Troubleshooting Guide
+
+When LiteLLM acts as an MCP proxy, traffic normally flows `Client → LiteLLM Proxy → MCP Server`, while OAuth-enabled setups add an authorization server for metadata discovery.
+
+For provisioning steps, transport options, and configuration fields, refer to [mcp.md](./mcp.md).
+
+## Locate the Error Source
+
+Pin down where the failure occurs before adjusting settings so you do not mix symptoms from separate hops.
+
+### LiteLLM UI / Playground Errors (LiteLLM → MCP)
+Failures shown on the MCP creation form or within the MCP Tool Testing Playground mean the LiteLLM proxy cannot reach the MCP server. Typical causes are misconfiguration (transport, headers, credentials), MCP/server outages, network/firewall blocks, or inaccessible OAuth metadata.
+
+<Image 
+  img={require('../img/mcp_tool_testing_playground.png')}
+  style={{width: '80%', display: 'block', margin: '0'}}
+/>
+
+<br/>
+
+**Actions**
+- Capture LiteLLM proxy logs alongside MCP-server logs (see [Error Log Example](./mcp_troubleshoot#error-log-example-failed-mcp-call)) to inspect the request/response pair and stack traces.
+- From the LiteLLM server, run Method 2 ([`curl` smoke test](./mcp_troubleshoot#curl-smoke-test)) against the MCP endpoint to confirm basic connectivity.
+
+### Client Traffic Issues (Client → LiteLLM)
+If only real client requests fail, determine whether LiteLLM ever reaches the MCP hop.
+
+#### MCP Protocol Sessions
+Clients such as IDEs or agent runtimes speak the MCP protocol directly with LiteLLM.
+
+**Actions**
+- Inspect LiteLLM access logs (see [Access Log Example](./mcp_troubleshoot#access-log-example-successful-mcp-call)) to verify the client request reached the proxy and which MCP server it targeted.
+- Review LiteLLM error logs (see [Error Log Example](./mcp_troubleshoot#error-log-example-failed-mcp-call)) for TLS, authentication, or routing errors that block the request before the MCP call starts.
+- Use the [MCP Inspector](./mcp_troubleshoot#mcp-inspector) to confirm the MCP server is reachable outside of the failing client.
+
+#### Responses/Completions with Embedded MCP Calls
+During `/responses` or `/chat/completions`, LiteLLM may trigger MCP tool calls mid-request. An error could occur before the MCP call begins or after the MCP responds.
+
+**Actions**
+- Check LiteLLM request logs (see [Access Log Example](./mcp_troubleshoot#access-log-example-successful-mcp-call)) to see whether an MCP attempt was recorded; if not, the problem lies in `Client → LiteLLM`.
+- Validate MCP connectivity with the [MCP Inspector](./mcp_troubleshoot#mcp-inspector) to ensure the server responds.
+- Reproduce the same MCP call via the LiteLLM Playground to confirm LiteLLM can complete the MCP hop independently.
+
+<Image 
+  img={require('../img/mcp_playground.png')}
+  style={{width: '80%', display: 'block', margin: '0'}}
+/>
+
+### OAuth Metadata Discovery
+LiteLLM performs metadata discovery per the MCP spec ([section 2.3](https://modelcontextprotocol.info/specification/draft/basic/authorization/#23-server-metadata-discovery)). When OAuth is enabled, confirm the authorization server exposes the metadata URL and that LiteLLM can fetch it.
+
+**Actions**
+- Use `curl <metadata_url>` (or similar) from the LiteLLM host to ensure the discovery document is reachable and contains the expected authorization/token endpoints.
+- Record the exact metadata URL, requested scopes, and any static client credentials so support can replay the discovery step if needed.
+
+## Verify Connectivity
+
+Run lightweight validations before impacting production traffic.
+
+### MCP Inspector
+Use the MCP Inspector when you need to test both `Client → LiteLLM` and `Client → MCP` communications in one place; it makes isolating the failing hop straightforward.
+
+1. Execute `npx @modelcontextprotocol/inspector` on your workstation.
+2. Configure and connect:
+   - **Transport Type:** choose the transport the client uses (Streamable HTTP for LiteLLM).
+   - **URL:** the endpoint under test (LiteLLM MCP URL for `Client → LiteLLM`, or the MCP server URL for `Client → MCP`).
+   - **Custom Headers:** e.g., `Authorization: Bearer <LiteLLM API Key>`.
+3. Open the **Tools** tab and click **List Tools** to verify the MCP alias responds.
+
+### `curl` Smoke Test
+`curl` is ideal on servers where installing the Inspector is impractical. It replicates the MCP tool call LiteLLM would make—swap in the domain of the system under test (LiteLLM or the MCP server).
+
+```bash
+curl -X POST https://your-target-domain.example.com/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
+```
+
+Add `-H "Authorization: Bearer <LiteLLM API Key>"` when the target is a LiteLLM endpoint that requires authentication. Adjust the headers, or payload to target other MCP methods. Matching failures between `curl` and LiteLLM confirm that the MCP server or network/OAuth layer is the culprit.
+
+## Review Logs
+
+Well-scoped logs make it clear whether LiteLLM reached the MCP server and what happened next.
+
+### Access Log Example (successful MCP call)
+```text
+INFO:     127.0.0.1:57230 - "POST /everything/mcp HTTP/1.1" 200 OK
+```
+
+### Error Log Example (failed MCP call)
+```text
+07:22:00 - LiteLLM:ERROR: client.py:224 - MCP client list_tools failed - Error Type: ExceptionGroup, Error: unhandled errors in a TaskGroup (1 sub-exception), Server: http://localhost:3001/mcp, Transport: MCPTransport.http
+  httpcore.ConnectError: All connection attempts failed
+ERROR:LiteLLM:MCP client list_tools failed - Error Type: ExceptionGroup, Error: unhandled errors in a TaskGroup (1 sub-exception)...
+  httpx.ConnectError: All connection attempts failed
+```

docs/my-website/sidebars.js

@@ -488,6 +488,7 @@ const sidebars = {
             "mcp_control",
             "mcp_cost",
             "mcp_guardrail",
+            "mcp_troubleshoot",
           ]
         },
         "anthropic_unified",