Skip to main content

​
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. 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 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. That confirms whether the gateway can reach the MCP server and attach an Authorization header, independent of control-plane OAuth token requests.
1

Mint an access token

Mint an access token using the same method as the working external client.
2

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.
3

Retry through the gateway

Retry tools/list or initialize through the gateway (for example from the UI or Playground or your client).
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.

​
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.

​
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.

​
Install and run

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

​
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.
1

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.
2

Select transport and URL

In the connection UI, choose the transport type and enter the MCP server URL.
3

Open Auth Settings

Open Auth Settings in the Inspector so you can configure how this client authenticates to the MCP server.
4

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.
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.