My Custom MCP Server Isn't Working — How Do I Troubleshoot It?

Last updated: March 21, 2026

Custom MCP server issues usually come down to one of five things: an invalid URL, an authentication problem, a connection timeout, tools not being discovered, or tool calls failing at runtime. This guide walks through each one with the exact errors you'll see and how to fix them.

Before You Start: Quick Checklist

Run through these first — they resolve the majority of custom MCP issues:

  1. Your server URL starts with https:// (HTTP is not supported)

  2. Your server is deployed and publicly accessible on the internet — not running on localhost

  3. Your server uses Streamable HTTP or SSE transport (STDIO is not supported)

  4. If your server requires auth, you've entered a valid, unexpired token in the credential config

  5. The server is actually running and responding — try opening the URL in a browser or hitting it with curl

Issue 1: "Failed to Connect to MCP Server"

What you see

  • When adding the server in Settings → Credentials, clicking Connect shows a toast error: Failed to connect to MCP server

  • Or the agent run log shows the server as unavailable

Common causes

  • The URL is unreachable — the server is down, the domain doesn't resolve, or a firewall is blocking access

  • The URL points to a private IP range, localhost, or loopback address. Gumloop blocks these for security (SSRF protection) and will return an invalid_mcp_server_url error

  • The URL is missing the https:// prefix. The frontend validates this and will show: URL must start with http:// or https:// — but only HTTPS actually works

  • An SSL/TLS certificate issue on your server (self-signed certs, expired certs)

How to fix it

  1. Verify the URL is correct, starts with https://, and points to a publicly routable address

  2. Test the URL from your own machine: curl -I https://your-server-url.com/sse — you should get a response

  3. If your server runs locally, you need to expose it via a tunnel service like ngrok or Cloudflare Tunnels and use the tunnel's public HTTPS URL

  4. If using a self-signed certificate, switch to a proper TLS cert (e.g., via Let's Encrypt)

Issue 2: Authentication Errors

What you see

  • The server connects but tool calls return auth errors

  • The agent's chat stream may abruptly stop with a message about authentication failure

  • The error MCP server credential not found. Add it in Settings > Credentials. appears if the credential was deleted or not configured

Common causes

  • The access token or API key you entered has expired or been revoked

  • The token doesn't have the right scopes or permissions for the tools you're trying to use

  • You're using the wrong auth format — for example, your server expects a custom header like X-API-Key but you entered the key in the "Access Token" field (which sends it as Authorization: Bearer)

  • The credential was set up as a personal credential but someone else is trying to run the agent

How to fix it

  1. Go to Settings → Credentials and find your custom MCP server credential

  2. Check that the access token is current and valid. If it's expired, generate a new one from your MCP server provider and update it

  3. Confirm you're using the right auth method:

    • If your server expects a Bearer token → put it in the Access Token / API Key field

    • If your server expects a custom header → use the Additional Header field in the format Header-Name: value

  4. If other team members need to use this server, set the credential as a team credential rather than personal

Issue 3: Tools Not Appearing

What you see

  • The server connects successfully but the agent doesn't seem to have any tools from it

  • Asking the agent to "list available tools" doesn't show your server's tools

  • The error Could not resolve MCP server configuration. or MCP server URL not found in credential. may appear

Common causes

  • Your MCP server doesn't properly implement the tools/list method (tool discovery). This is an MCP protocol requirement

  • The credential was saved but the URL field is empty or malformed

  • The server returns an empty tool list — this can happen if the server requires initialization or the tools are behind a login that wasn't completed

  • The server is behind a load balancer or gateway that intercepts the MCP handshake

How to fix it

  1. Test your server's tool discovery independently using an MCP client (like the MCP Inspector) to verify it responds to tools/list

  2. Go to Settings → Credentials, edit your MCP server credential, and verify the URL field is populated and correct

  3. Ask your agent: "What tools do you have available?" — if the server connected but returned no tools, the agent will tell you it has no tools from that server

  4. Check your server logs for errors during the tool listing request

Issue 4: Connection Timeouts

What you see

  • The agent log shows a message like: Tool call to [server].[tool] timed out after [N]s

  • The initial connection may fail silently, and the agent says tools from that server are unavailable

  • The agent receives a system warning: The following MCP servers could not be connected and their tools are unavailable: [server name]

Common causes

  • Your server is slow to respond — Gumloop uses a 10-second timeout for the initial connection handshake

  • A tool call is taking too long — the default tool call timeout is 5 minutes (300 seconds)

  • The server is under heavy load, experiencing network latency, or the hosting provider has cold-start delays

  • DNS resolution is slow for your server's domain

How to fix it

  1. Test your server's response time: time curl -X POST https://your-server.com/sse — the initial handshake should complete in under 10 seconds

  2. If your server has cold starts (common with serverless hosting like Railway, Render, or AWS Lambda), consider warming it before agent runs or switching to an always-on deployment

  3. For slow tool calls, check if the underlying operation can be optimized — large database queries, slow APIs, or heavy computation can exceed the 5-minute timeout

  4. If the server is on a free-tier hosting service, it may sleep after inactivity. Upgrade to a paid tier or add a keep-alive mechanism

Issue 5: Tool Calls Fail at Runtime

What you see

  • The agent connects and discovers tools, but individual tool calls return errors

  • You may see Error from MCP tool in the agent's response

  • Or the more detailed: ERROR EXECUTING MCP TOOL in the run logs

Common causes

  • The tool received unexpected input — the AI may be passing parameters in a format your server doesn't expect

  • The tool's underlying service (database, API) is down or rate-limited

  • Your server has a bug in a specific tool handler

  • JSON parsing errors — the server returned a response that isn't valid JSON or doesn't match the expected MCP format

How to fix it

  1. Check your MCP server's logs for the specific error — the server-side stack trace will be much more informative than the Gumloop error message

  2. Test the failing tool directly using an MCP Inspector or test client with the same parameters the agent is sending

  3. Make sure your tool handlers return valid MCP responses. Refer to the MCP Tools specification for the expected response format

  4. If the issue is the AI sending wrong parameters, improve the tool's description and parameter schemas in your server — the AI relies on these to determine what to pass

Model-Specific Behavior to Be Aware Of

How your custom MCP server runs depends on which AI model the agent uses:

  • With OpenAI models (GPT-4.1, GPT-5) and Anthropic models (Claude): the provider connects to your MCP server directly (native MCP). Your server's URL and credentials are passed to the provider

  • With Gemini and Groq models: Gumloop acts as a proxy — it connects to your server, discovers tools, and presents them to the model as regular function calls. Gumloop executes tool calls on your behalf

If your server works with one model but not another, this difference in execution path is likely the reason. The "Additional Header" field is only supported with backend-connector models (Gemini, Groq) — native MCP providers (OpenAI, Anthropic) may not forward custom headers.

Still Need Help?

If none of the above resolved your issue, reach out to support at support@gumloop.com. Include the following to help us diagnose faster:

  • Your MCP server URL (or a redacted version)

  • Agent Link

  • The AI model your agent is using

  • The exact error message you're seeing

  • Whether the issue is during connection, tool discovery, or tool execution

Related Docs