Debug connectors

The Connectors Debugger tests an MCP server before you register it as a connector. It checks that Studio can reach the server, that authentication works, and that the server exposes valid tools, and it reports the errors it finds.

i
Information

The Connectors Debugger is in Public Preview. Its checks and error details can change.

Before you start

Before you start

You need:

  • Permission to create connectors in your Studio workspace. Without it, Studio shows a permission message instead of the Debugger.
  • The URL of the MCP server that you want to test.

If the server requires authentication, prepare one of the following:

  • A static HTTP header, such as Authorization: Bearer <token>.
  • OAuth2 client credentials for the server.

If the server uses OAuth2, add this redirect URI to your OAuth application:

https://console.mistral.ai/build/connectors/debugger/oauth-callback
i
Information

The Debugger doesn't store the credentials that you enter. They last only for the current session.

Open the Connectors Debugger

Open the Connectors Debugger

  1. Open Studio.
  2. In the navigation menu, click Connectors.
  3. Click Debugger.

You can also open the Debugger directly: Studio›Connectors›Debugger ↗

Configure the test

Configure the test

  1. In the URL field, enter the MCP server URL.
  2. If the server requires credentials, click the settings icon next to Run diagnostic:
    • In Credentials, select Custom header or OAuth 2.0.
    • For a custom header, set Header name to Authorization and Header value to Bearer <token>.
    • For OAuth, enter Client ID and Client Secret.
  3. Click Run diagnostic.
Warning

Only test servers that you trust. The Debugger sends the headers and credentials that you configure to the server URL.

Run a diagnostic

Run a diagnostic

The Debugger runs the diagnostic and shows a report. To repeat the test after you change the URL or the credentials, click Run again.

When a step fails, the report names the step and adds troubleshooting details. Depending on the failure, the report can include:

  • Likely cause
  • Suggested fix
  • Raw response
  • Copy as curl
  • Headers
  • Body
  • A JSON report for the failed step

For example, if the server responds with HTML instead of an MCP JSON-RPC response, the report can show The server responded but does not appear to be an MCP server as the likely cause and Verify the URL points to an MCP server, not a regular web page or REST API as the suggested fix.

A failed step report can look like this:

{
  "step": "transport_detection",
  "status": "error",
  "duration": 259,
  "data": {
    "attempt": {
      "request": {
        "method": "POST",
        "url": "https://chaos-mcp.example.com/"
      },
      "response": {
        "status": 200,
        "headers": {
          "content-type": "text/html; charset=utf-8"
        },
        "body": "<!DOCTYPE html><html lang=\"en\">..."
      }
    }
  },
  "error": {
    "type": "not_mcp_server"
  }
}
Review a successful test

Review a successful test

When all checks pass, the report shows that the MCP server is ready. It includes the MCP protocol version, a View official docs link, summary metrics, the server instructions when the server returns them, and the discovered MCP content.

A successful report can include:

  • MCP server ready
  • Protocol 2025-11-25
  • View official docs
  • Tools: the number of tools discovered
  • Prompts: the number of prompts discovered
  • Resources: the number of resources discovered
  • Duration: how long the validation took
  • Checks: the number of checks that passed, such as 3/3
  • Instructions: server instructions when the MCP server returns them

The Tools section lists the discovered tools. To filter them, use Search.... To inspect them, select Interactive. For example, a test server might return tools named echo, add, and current_time. Selecting echo shows Echo back the provided message. as the description and shows the input schema:

{
  "type": "object",
  "properties": {
    "message": {
      "description": "Text to echo",
      "type": "string"
    }
  },
  "required": ["message"]
}
Troubleshoot typical MCP errors

Troubleshoot typical MCP errors

Start with the report: it shows the failed step, the Likely cause, and the Suggested fix. The following cases explain common MCP server issues that can appear in the report.

Next steps after a successful test

Next steps after a successful test

The Debugger doesn't register the server. To register it as a connector, see Manage connectors, or follow the Quickstart.