MCP Troubleshooting | Fix MCP Server Not Showing Tools

You added an MCP server, the client says it's connected, and... nothing. No tools. Or a red dot. Or "0 tools found." This is the single most common MCP frustration, and it almost always comes down to one of a handful of causes.

This guide is organized by symptom. Find the one that matches what you're seeing, work the fix, and move on. It applies whether you're using Claude Desktop, Cursor, ChatGPT, Zapier, or any other MCP client. (New to MCP entirely? Read what is an MCP server first.)

60-Second Triage

Before diving into a specific symptom, run these four checks — they catch the majority of cases:

Did you fully restart the client? Claude Desktop and Cursor read MCP config at launch. Closing the window isn't enough — quit completely (Cmd+Q on Mac) and reopen.
Is the endpoint URL exactly right? One truncated character or a stale copy breaks everything. Recopy it from your provider's dashboard.
Is the underlying data source actually reachable? If you're using a managed gateway like Synra, open the dashboard and re-run Test connection. A failing database connection looks like a broken MCP server from the client's side.
Open the endpoint URL in a browser. A JSON response (even an error like {"jsonrpc":"2.0","error":{...}}) means the server is alive and reachable. A 404, timeout, or connection-refused means the URL or network is the problem, not the client.

If none of those fix it, find your symptom below.

Symptom: Connected, but no tools appear

This is the big one. The client shows the server as connected (or at least present), but the tool list is empty.

Cause 1 — Content negotiation / transport mismatch. Some MCP clients are strict about how the server replies. They send an Accept: text/event-stream header and expect a Server-Sent Events (SSE) response; if the server replies with plain JSON, the strict client treats the tool list as empty. This is exactly the failure mode Zapier's MCP Client hit against gateways that only spoke JSON. A correct server negotiates: SSE when the client asks for it, JSON otherwise. (Synra does this automatically — if you're self-hosting, this is the first thing to check.)

Cause 2 — The tool list genuinely is empty. If the data source behind the server has no tables, no schema access, or the connection is in a failed state, there's nothing to advertise. For a managed gateway, re-run the connection test. For a self-hosted server, check its logs for credential or permission errors at startup.

Cause 3 (ChatGPT specifically) — tools greyed out in Developer mode. A known ChatGPT beta quirk, especially on Plus accounts: the connector is created but every tool is disabled. Click Refresh on the connector first. Confirm Developer mode is actually toggled on (Settings → Apps & Connectors → Advanced settings). See the ChatGPT setup guide for the full flow.

How to isolate client vs server: point a second, known-good client at the same URL. If Claude Desktop sees the tools but Cursor doesn't, it's a client/config issue. If no client sees them, it's the server or the data source. The MCP Inspector (npx @modelcontextprotocol/inspector) is the neutral referee — point it at your URL and it'll show you the raw tools/list response.

Symptom: Red status / "Server transport closed" / "failed to connect"

The client tried to reach the server and couldn't establish a session.

Open the URL in a browser. 404 or connection error → the URL is wrong or the server is down. Recopy from the dashboard.
Check for localhost in a remote context. If you (or your host) accidentally configured a localhost/127.0.0.1 URL, a remote client can't reach it. This also bites deployments behind a proxy — an internal port (like :8080) leaking into a public URL produces exactly this. The URL the client uses must be the public one.
HTTPS required. Most clients refuse plain http:// for remote servers. The endpoint must be https://.
Firewall / IP allowlist. If your database or server sits behind an allowlist, the gateway's outbound IPs (or the client) may be blocked.

Symptom: Tools show up, but calling one fails

Discovery worked, but the actual query errors out.

"Credentials not configured" or similar. The MCP layer is fine; the data source behind it isn't. For a managed gateway, the saved connection is probably in a failed state — re-test it in the dashboard and fix the credentials there, not in the client.
"SSL connection required." Common with Neon, Heroku, Supabase, and other managed Postgres hosts. Add ?sslmode=require to the connection string and re-test. Most providers include this by default in the string they hand you.
Permission denied on a table. The database user the server connects as lacks SELECT on that table. Grant it, or point at a user/role that has the access you expect.
Timeouts on big queries. A query returning millions of rows can exceed the client or gateway timeout. Ask for an aggregate or a LIMIT instead of the full table.

Symptom: The client doesn't list the connector at all

You added it, but it's not even showing up.

Claude Desktop. The current flow is Settings → Connectors → Add custom connector (the older JSON-config-file method is deprecated for most users). After adding, fully quit and relaunch Claude. See Connect Claude to PostgreSQL for the exact steps.

Cursor. Config lives in ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project). The most common breakage is invalid JSON — validate with cat ~/.cursor/mcp.json | jq .. A trailing comma after the last entry is the classic culprit. Then fully restart Cursor. Full walkthrough in Connect Cursor to PostgreSQL.

ChatGPT. Custom connectors require Developer mode on a paid plan, set up on the web app (not mobile). If there's no "Create" / "Add custom connector" button, Developer mode isn't enabled. See Connect ChatGPT to Your Database.

Symptom: The agent won't use the tools

Everything's connected, the tools are listed, but the model answers from memory instead of querying.

Invoke it explicitly the first time. In Cursor, type @ and pick the MCP server. In ChatGPT, select the connector from the + menu in the composer. Once the model has "seen" the tool surface in a conversation, it'll reach for it automatically on follow-ups.
Give the connector a good description. ChatGPT (and others) use the connector's description text during tool discovery. "Read-only access to my production Postgres — use for querying tables and data" works far better than a blank or vague description.
Ask a concrete, data-shaped question. "What's in my database?" is vague. "List the tables in my database" maps cleanly to a tool call.

The Neutral Test: MCP Inspector

When you can't tell whether the problem is the client or the server, take the client out of the equation:

npx @modelcontextprotocol/inspector

Point it at your endpoint URL. The Inspector speaks raw MCP and shows you:

whether initialize succeeds
the exact tools/list response (your tools, or an empty array)
the result of calling a tool by hand

If the Inspector sees your tools and your client doesn't, the problem is the client's config or transport handling. If the Inspector also sees nothing, the problem is upstream — the server or the data source behind it.

When It's Just Easier to Use a Managed Gateway

A large share of these problems — content negotiation, transport mismatches, localhost leaks, HTTPS, credential handling, keeping the server reachable — are infrastructure problems, not MCP problems. They're the cost of running your own server.

A managed gateway like Synra handles the transport correctly (SSE and streaming HTTP, negotiated per client), stays reachable over HTTPS, encrypts your credentials, and gives you a single URL that behaves identically across Claude, Cursor, and ChatGPT. When something's off, there's one place to look — the connection test in the dashboard — instead of a stack of layers to bisect.

If you've been fighting a self-hosted server, it might simply not be worth the time. The self-hosted vs managed comparison lays out where each makes sense.

Still stuck after all this? Email hello@mcpserver.design with the symptom and what you've tried — we read every one.

Related guides: