> ## Documentation Index
> Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Troubleshooting Guide

> General guide to troubleshoot MCP-related issues on TrueFoundry.

## Before you debug on the gateway

Before debugging an issue on the MCP Gateway, confirm you can connect to the MCP server directly with [MCP Inspector](#debug-with-mcp-inspector).

If the Inspector connects successfully, compare that working configuration with the MCP server registered in TrueFoundry:

* **MCP server URL** - the endpoint the gateway calls
* **Auth data** - auth type and credentials (API key, OAuth2, token passthrough, etc.)
* **Traces** - open [Request Traces](/docs/ai-gateway/fetch-request-logs-trace-inspection) and check for errors on the failing request

## Downstream MCP server returns 401

A **401** from the downstream MCP server means the request reached the MCP server without a valid Bearer token, or the token was rejected.

Use the steps below to separate gateway → MCP connectivity issues.

## Verify gateway connectivity

When OAuth-backed MCP calls fail through TrueFoundry but work from an external client, temporarily replace OAuth2 with a static Bearer token - see [Auth Overrides](/docs/ai-gateway/mcp/mcp-server-auth-overrides). That confirms whether the gateway can reach the MCP server and attach an `Authorization` header, independent of control-plane OAuth token requests.

<Steps>
  <Step title="Mint an access token">
    Mint an access token using the same method as the working external client.
  </Step>

  <Step title="Add auth override">
    In TrueFoundry, go to the MCP server:

    1. Go to the **Auth Overrides** tab and click **Add override**.
    2. Enter the subject and the access token.

    Click **Submit**. For more information, see [Auth Overrides](/docs/ai-gateway/mcp/mcp-server-auth-overrides).
  </Step>

  <Step title="Retry through the gateway">
    Retry `tools/list` or `initialize` through the gateway (for example from the UI or Playground or your client).
  </Step>
</Steps>

| Result                                            | What it means                                                                                           |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Success (`initialize` returns 200, tools listed)  | Gateway → MCP path works. Focus on OAuth token requests from the control plane.                         |
| **401** with the same token that works externally | Gateway may not be sending the header, the URL may be wrong, or the token is not accepted on that path. |
| Timeout or connection error                       | Treat as a [network or allowlist issue](#gateway-reachability-to-the-downstream-mcp-url).               |

<Warning>
  Remove the temporary auth override after the isolation test. Do not leave a long-lived Bearer token override in place for production use unless that is your intended auth model.
</Warning>

## Gateway reachability to the MCP URL

TrueFoundry Gateway must reach the MCP URL from the cluster or network where the gateway runs.

Verify the following:

* A working external script or MCP Inspector session proves reachability from **your** network. It does **not** prove the MCP endpoint is reachable from TrueFoundry.
* Check whether the MCP host requires IP allowlisting, private link, VPN, or mTLS for the gateway's egress path. For private networks, see [Connect Private Models and MCP Servers](/docs/ai-gateway/connect-private-models-mcp-servers).

## Debug with MCP Inspector

MCP Inspector is an interactive tool for testing and debugging MCP servers over different transports. For a full feature overview, see the [MCP Inspector documentation](https://modelcontextprotocol.io/docs/tools/inspector).

### Install and run

Run the Inspector with `npx` (nothing to install globally):

```bash theme={"dark"}
npx @modelcontextprotocol/inspector
```

### Debug MCP OAuth issues

When an MCP server uses **OAuth2**, use the Inspector to verify that OAuth-based connectivity works before you troubleshoot clients or the Playground.

<Steps>
  <Step title="Open the Inspector from the terminal link">
    After you start the Inspector with `npx @modelcontextprotocol/inspector`, click the **link** printed in the terminal (usually a local URL) to open the Inspector UI in your browser.
  </Step>

  <Step title="Select transport and URL">
    In the connection UI, choose the **transport** type and enter the MCP server **URL**.
  </Step>

  <Step title="Open Auth Settings">
    Open **Auth Settings** in the Inspector so you can configure how this client authenticates to the MCP server.
  </Step>

  <Step title="Run Quick OAuth Flow">
    Use **Quick OAuth Flow**. Press **Continue** and complete the OAuth prompts step by step. If this flow completes and you can list tools or call resources, OAuth-based MCP connectivity is working for that URL and configuration.
  </Step>
</Steps>

<Note>
  If OAuth works in the Inspector but fails in an IDE or agent, compare redirect URIs and allowed origins in your OAuth provider with the values documented for your MCP server. For gateway-side behavior, see [Authentication and Security](/docs/ai-gateway/mcp/mcp-gateway-auth-security).
</Note>