docs: add quick-start debug command to MCP troubleshoot page

docs/my-website/docs/mcp_troubleshoot.md

@@ -6,6 +6,39 @@ When LiteLLM acts as an MCP proxy, traffic normally flows `Client → LiteLLM Pr
 
 For provisioning steps, transport options, and configuration fields, refer to [mcp.md](./mcp.md).
 
+## Quick Start: Debug with One Command
+
+The fastest way to debug MCP issues is to enable **debug headers**. Run this curl against your LiteLLM proxy and check the response headers:
+
+```bash
+curl -si -X POST http://localhost:4000/{your_mcp_server}/mcp \
+  -H "Content-Type: application/json" \
+  -H "x-litellm-api-key: Bearer sk-YOUR_KEY" \
+  -H "x-litellm-mcp-debug: true" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
+  2>&1 | grep -i "x-mcp-debug"
+```
+
+This returns masked diagnostic headers that tell you exactly what's happening with authentication:
+
+```
+x-mcp-debug-inbound-auth: x-litellm-api-key=Bearer****1234
+x-mcp-debug-oauth2-token: Bearer****ef01
+x-mcp-debug-auth-resolution: oauth2-passthrough
+x-mcp-debug-outbound-url: https://mcp.atlassian.com/v1/mcp
+x-mcp-debug-server-auth-type: oauth2
+```
+
+If you see `SAME_AS_LITELLM_KEY` in `x-mcp-debug-oauth2-token`, your LiteLLM API key is leaking to the MCP server instead of an OAuth2 token. See [Debugging OAuth](./mcp_oauth#debugging-oauth) for the fix and other common issues.
+
+For Claude Code, add the debug header to your MCP config:
+
+```bash
+claude mcp add --transport http my_server http://localhost:4000/my_mcp/mcp \
+  --header "x-litellm-api-key: Bearer sk-..." \
+  --header "x-litellm-mcp-debug: true"
+```
+
 ## Locate the Error Source
 
 Pin down where the failure occurs before adjusting settings so you do not mix symptoms from separate hops.
@@ -13,7 +46,7 @@ Pin down where the failure occurs before adjusting settings so you do not mix sy
 ### 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 
+<Image
   img={require('../img/mcp_tool_testing_playground.png')}
   style={{width: '80%', display: 'block', margin: '0'}}
 />
@@ -22,7 +55,7 @@ Failures shown on the MCP creation form or within the MCP Tool Testing Playgroun
 
 **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.
+- From the LiteLLM server, run a [`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.
@@ -43,7 +76,7 @@ During `/responses` or `/chat/completions`, LiteLLM may trigger MCP tool calls m
 - 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 
+<Image
   img={require('../img/mcp_playground.png')}
   style={{width: '80%', display: 'block', margin: '0'}}
 />
@@ -55,9 +88,9 @@ LiteLLM performs metadata discovery per the MCP spec ([section 2.3](https://mode
 - 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.
 
-## Debug Headers (OAuth)
+## Debugging OAuth
 
-For OAuth-related debugging, LiteLLM supports opt-in debug response headers that show masked authentication diagnostics. See [Debugging OAuth](./mcp_oauth#debugging-oauth) for setup and common issues.
+For detailed OAuth2 debugging — including debug header reference, common misconfigurations, and example output — see [Debugging OAuth](./mcp_oauth#debugging-oauth).
 
 ## Verify Connectivity
 
@@ -70,7 +103,7 @@ Use the MCP Inspector when you need to test both `Client → LiteLLM` and `Clien
 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>`.
+   - **Custom Headers:** e.g., `x-litellm-api-key: Bearer <LiteLLM API Key>`.
 3. Open the **Tools** tab and click **List Tools** to verify the MCP alias responds.
 
 ### `curl` Smoke Test
@@ -83,7 +116,7 @@ curl -X POST https://your-target-domain.example.com/mcp \
   -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.
+Add `-H "x-litellm-api-key: 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