← Back to Blog

2026-09-22 • Updated 2026-09-26 • 7 min read • Fix

How to Debug an MCP Server

Debug an MCP server in a fixed order: prove the URL with curl, match the client's tools, wait for indexing, then test a known question and a miss.

The most likely reason an MCP server seems broken is that the AI client never called it, so you end up editing content that was never retrieved. The fix is to debug in a fixed order and stop at the first step that fails: prove the URL returns a tool list with curl, confirm the client shows those same tools, wait for indexing to finish, then ask one question you can check and one the sources do not cover.

By the end you will know which of four problems you have (the connection, the client config, an unfinished index, or the content itself) and the one change to make next.

Why the order matters

A wrong answer and a missing connection look the same from the chat window. Both give you a fluent reply, so first check whether the server was asked at all.

Change one thing at a time. Edit the URL, the token, and a heading in one pass and a working answer cannot tell you which change fixed it.

Use a question you can already answer. Without a fact you can check, every reply looks plausible.

Throughout this post, the example is an API reference that documents a createUser endpoint and its rate limit. That gives you a known question ("What is the rate limit on createUser?") and a clear miss ("What is the office wifi password?").

How to run the five checks

Context MCP Studio is the no-code builder on Appa Tools. Open your server on the dashboard and copy its URL from the setup page. You do not write any code to debug it.

  1. The URL answers. Run tools/list with curl. It should return the tools you selected in the wizard. If it does not, stay on Fix an MCP server that isn't connecting until curl is boring. An empty tool list means no tools were selected, or you are calling a different server than the one you edited.
  2. The client shows those same tools. Cursor, Claude Desktop, Windsurf, and Codex read MCP config when a session starts, so restart the client or open a new session after any change. Each client has its own page: not showing up in Claude, not showing up in Cursor, and connect an MCP server to Codex.
  3. Indexing has finished. The endpoint exists as soon as you deploy, but the source keeps indexing in the background. Wait until the dashboard shows the source as complete. Judging answers before that measures a crawl in progress, not your docs.
  4. A question you can answer yourself. Ask for the createUser rate limit and open the citation. The cited page should be the one that states it.
  5. A question the sources do not cover. The server should say so plainly instead of inventing an answer.

For step 1 on a public server, this is the call:

curl -X POST https://appatools.com/mcp-studio/api/mcp/your-server \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

A private server needs its mcps_live_ token as a bearer header. The exact format is in the private servers guide.

What the dashboard tells you on each plan

Every plan shows whether a client called the server. The free dashboard shows request volume, success, response time, requests over time, and a breakdown by tool, source, and client. If your test question does not appear there, the client answered without asking the server, which sends you back to step 2.

Success means the call completed, not that the passage was right. To see the question text, you need Core analytics. To see the exact passage each request returned, you need Action. The full table is in What the questions people ask your docs can tell you.

Check that it works

Ask the question the sources do not cover and look for a reply like this:

You: What is the office wifi password?

Assistant: Nothing in this server's content covers an office wifi password. The closest material is the upload authentication guide, which is a different subject.

A confident paragraph on that question usually means the client did not call the server. Look for a tool call beside the reply, then confirm the request appears on the dashboard.

Note the question, the cited page, and the one change you made, so you can rerun the same pair after every edit.

What to do when the known question still misses

A miss on step 4 is a content or tool choice problem. The connection is proven and the index is complete, so the answer either is not in the source or sits under a heading that does not match the question. That path is Fix an MCP server returning the wrong information.

A retrieval rule counts as your one change. If you add a rule that tells the server which source to prefer for a kind of question, test it with the same pair of questions before changing anything else. See retrieval rules.

Frequently asked questions

Why does my MCP server connect but give wrong answers?

Usually the answer is not in the source, indexing has not finished, or the detail sits under a heading that does not match the question. Wait for the dashboard to show the source as complete, then ask a question you already know the answer to and open the citation. If the cited page is wrong, the fix is in the content or the tools you selected, not the connection.

How do I know if my AI client actually called the MCP server?

Look for a tool call or connector activity beside the reply, then check that the request appears on the MCP Studio dashboard, which shows every call on every plan. If nothing appears, the client answered from general knowledge without asking your server.

Why does my MCP server return an empty tool list?

An empty tool list means no tools were selected for that server, or you are calling a different server than the one you edited. Compare the server name in the URL with the one on your dashboard. Then confirm the tools you chose in the wizard are attached to that server.

Do I need to wait for indexing before testing my MCP server?

You can connect as soon as you deploy, because the endpoint exists right away. You should wait for indexing to finish before judging the answers, since a source that is still indexing has not been fully read yet. The dashboard shows when each source is complete.

Can I see which questions people asked my MCP server?

The free dashboard shows how many requests arrived, whether they succeeded, how long they took, and which tool, source, and client were involved. The text of each question is part of Core analytics. The exact passage returned for each request is part of Action analytics.

Debug your server with MCP Studio

Open your server in MCP Studio and run the five checks in order, stopping at the first one that fails. The dashboard shows every call on every plan, so one known question and one deliberate miss tell you exactly what to change next.

Where to go next