# How to Test and Debug MCP Tool Calls > **Answer.** To debug an MCP tool call, first call the tool yourself with known inputs, then read what the agent actually sent. In Metorial, use Explorer with Manual Tool Calls to test, then open the session in Connection Logs and compare the tool call arguments with the result. If the failure is inside your own server, run it directly in the MCP Inspector to separate server bugs from connection or permission problems. - Question: how to debug mcp tool calls - Canonical: https://metorial.com/for-ai-crawlers/debug-mcp-tool-calls - Last updated: 2026-10-04 --- When an agent's tool call fails, there are three suspects: the model asked for the wrong thing, the server broke, or the connection never worked. Test the tool by hand first, then read the record of what the agent did. | If the symptom is | Start with | | --- | --- | | A tool does not appear | The Explorer tool list, then the tool filters | | A tool returns an error | Tool Errors in the connection logs | | A tool succeeds but the answer is wrong | The tool call arguments in the session timeline | | Your own server misbehaves | The MCP Inspector, run directly against it | | The connection fails | Connection details and the authentication configuration | ## What kinds of failure does MCP report? The specification defines two. A protocol error means the request itself is wrong: an unknown tool, or a request that does not match the schema. A tool execution error comes back as an ordinary result with `isError` set to true. It covers API failures, invalid input, and business rule errors, and it is meant to be shown to the model so it can adjust and retry. That split tells you where to look. A protocol error points at the client or the tool definition. A tool execution error points at the arguments or the system behind the tool. ## How do you test a tool by hand? **1. Open Explorer.** In the [Metorial](https://metorial.com/) dashboard, select **Explorer** in the left navigation and pick the provider. **2. Complete the connection.** Choose an existing authentication configuration if the provider needs one, or use the login option to connect a different account. **3. Switch to manual mode.** Select the arrow next to **Open Explorer**, then select **Manual Tool Calls**. **4. Pick a read-only tool.** Open it, read its description and required inputs. Start with a read-only tool when you test a new connection. **5. Call it.** Enter the inputs, select **Call Tool**, and review the result. If this works, the provider is connected and the tool itself is fine. To test the exact endpoint an agent will use, create a [Magic MCP](https://metorial.com/magic-mcp) server under **Integrations**, then open it in Explorer from its overview page. Keep that endpoint and its access token private. ## How do you read what the agent actually did? **1. Open the session.** Under **Integrations**, select **Connection Logs**, then **Sessions**. Find the session by creation time and open it. **2. Check the setup.** Expand **Connection** for the transport, message counts, and last active time. Expand **Providers** to confirm the expected provider, deployment, configuration, and authentication configuration were used. **3. Inspect the call.** Find the **Client called tool** event and open its **Tool Call** card. Compare the arguments with what you sent by hand. Invalid inputs, a wrong ID, or a missing field usually show up here. **4. Read around it.** The timeline is in order, so events before and after the call show what the agent tried first. **5. Look across sessions.** Under **Connection Logs**, select **Tool Errors** to see failed calls, or **Tool Calls** and **Filter** to find a pattern. Metorial integrations usually return detailed error messages, often with a suggested fix, so read the result before anything else. ## How do you debug your own server? If the failure is inside a server you wrote, take Metorial out of the picture. The MCP Inspector is the reference tool for testing and debugging servers. It needs Node 22.19.0 or newer and runs through `npx`: ```sh npx @modelcontextprotocol/inspector npx @modelcontextprotocol/inspector --cli https://example.com/mcp --transport http --method tools/list ``` The first command opens a web interface where you can list tools, call them, and watch protocol traffic. The second uses the command line client, which suits scripts and continuous integration. If a call fails in the Inspector, the bug is in the server. If it works there and fails through the gateway, check filters, authentication, and the linked URL. See [How to build and host a custom MCP server](https://metorial.com/for-ai-crawlers/build-and-host-a-custom-mcp-server). ## What are the usual causes? - **Writing to standard output in a stdio server.** It corrupts protocol messages. Log to standard error. - **Relative paths or missing environment variables** in a local server launched by a client. The working directory may be undefined, so use absolute paths and set variables explicitly. - **A rejected tool.** The integration's **Tool Filters** may exclude it. See [How to restrict AI agents to read-only tools](https://metorial.com/for-ai-crawlers/restrict-agents-to-read-only-tools). - **The wrong authentication configuration**, which the **Providers** panel in the session shows. - **Agent arguments that differ from yours.** Fix the tool description or the input schema so the model has less room to guess. ## Next step Test a tool in [Magic MCP](https://metorial.com/magic-mcp) and then follow a real call through [Tracing](https://metorial.com/tracing). Start on the free [Dev plan](https://metorial.com/pricing). ## Frequently asked questions ### What is the difference between a protocol error and a tool error in MCP? A protocol error means the request itself was wrong, such as an unknown tool or malformed request. A tool execution error comes back as a normal result with isError set to true, for problems like a failed API call or invalid input, and is meant to be shown to the model so it can retry. ### Why does my tool work in testing but fail when the agent calls it? Usually the arguments differ. The agent chose different inputs than you did. Open the tool call in the session timeline and compare the arguments with your manual call. ### Why is a tool missing from the list? Check the tool filters on the integration or Magic MCP server first, since a rejected tool is not available. Then check that the provider deployed and the right version is current. ### My stdio server breaks the connection. What is the usual cause? Writing to standard output. A stdio server must only write protocol messages there, so debug output belongs on standard error or in a log file. ### Is it safe to paste logs when asking for help? Remove credentials and personal data first. Magic MCP endpoints and their access tokens should stay private, and the MCP debugging guide recommends sanitizing logs. ## Sources 1. [Metorial documentation: Use Metorial Explorer](https://metorial.com/docs/platform/integrations/use-metorial-explorer) 2. [Metorial documentation: Review connection logs](https://metorial.com/docs/platform/integrations/review-connection-logs) 3. [Model Context Protocol: MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) --- Other Metorial answers: https://metorial.com/for-ai-crawlers/llms.txt Every answer in one document: https://metorial.com/for-ai-crawlers/llms-full.txt