Interactive MCP troubleshooting guideUpdated Jul 19, 2026By Editorial Automation Desk

MCP Server Not Showing Tools? Diagnose tools/list in 8 Checks

Fix an MCP server that is missing, connected with zero tools, stale, filtered, or visible but never called across Claude Code, Cursor, GitHub Copilot, and other clients.

Best for: Developers, MCP server authors, platform teams, and AI coding tool administrators.
Use this guide to: Diagnose why an MCP server is not showing tools and identify the first failing layer without widening permissions or reinstalling everything.

Quick Answer

If an MCP server is not showing tools, do not start by reinstalling the client. Prove each layer in order: confirm the client loaded the server config, reproduce the process or HTTP transport, complete initialization, and inspect tools/list in MCP Inspector. If Inspector lists the tools, the server works and the remaining fault is usually client scope, authentication, a tool allowlist or denylist, stale discovery, or on-demand tool loading. A visible tool that is never called is a selection or permission problem, not a discovery problem.

Verified 2026-07-19

MCP tool discovery debugger

Choose the exact symptom. The result starts at the first layer that can prove or disprove the failure.

SymptomClientTransport

Recommended first move

Prove tools/list outside the client

Check: Open the server in MCP Inspector and inspect the Tools tab, which exercises tool discovery independently of the target client.
Proof: The response contains the expected tool names, descriptions, and valid input schemas.
Fix: Register the missing tools, implement tools/list, repair invalid schemas, or remove server-side filtering that returns an empty list. If Inspector passes, continue to client policy and filters.
Client note: In Claude Code, use /mcp to inspect status and tool count. A connected server with zero tools is different from Tool Search deferring schemas until needed.
Transport note: For stdio, reproduce the exact command with the same arguments and environment. Use absolute paths and keep every diagnostic message off stdout.

Download debug worksheet Open official MCP Inspector guide

Crawlable fault tree

8 checks from config to invocation

Run the checks in order unless your symptom already proves an earlier layer passed.

Layer	Symptom	Test	Pass condition	Fix
1. Client configuration	The server is absent from the client's MCP status view.	Validate the configuration syntax, scope, server name, command or URL, and whether the client loaded that configuration source.	The named server appears in the client status view, even if it is still connecting or failed.	Correct the active config file or scope, avoid reserved or duplicate names, approve project config when required, then reload the client.
2. Process or transport	The server is configured but never connects.	Run the exact stdio command outside the client, or inspect the HTTP response, authentication status, session headers, and server logs.	The process stays alive or the endpoint accepts an MCP connection without an immediate transport error.	Use absolute executable and file paths, provide required environment variables, repair permissions, or correct the HTTP URL and authentication.
3. Stdio framing	The local process starts but the client reports JSON-RPC parse errors or disconnects.	Check that protocol messages are the only content written to stdout; send diagnostics to stderr.	The client receives complete JSON-RPC messages without banners, debug text, or other stdout noise.	Move logs from stdout to stderr and remove startup banners or wrappers that alter protocol framing.
4. Initialization handshake	The transport opens, but capabilities never become available.	Inspect the initialize response, negotiated protocol version, declared server capabilities, and the initialized notification.	Initialization completes and the server declares the tools capability when it intends to expose tools.	Update the MCP SDK or server implementation so initialize and notifications/initialized complete with compatible capabilities.
5. Tool discovery	The client says connected but shows zero tools.	Open the server in MCP Inspector and inspect the Tools tab, which exercises tool discovery independently of the target client.	The response contains the expected tool names, descriptions, and valid input schemas.	Register the missing tools, implement tools/list, repair invalid schemas, or remove server-side filtering that returns an empty list.
6. Client policy and filters	Inspector lists tools, but the target client does not expose them.	Check the client's enabled-tool list, allowlist or denylist, custom-agent tool policy, server scope, and authentication state.	The expected tool is enabled for the current client, workspace, agent, and session.	Enable the named tool or server in the correct scope, complete authentication, and remove a conflicting deny rule without widening unrelated access.
7. Refresh and list changes	New or renamed tools do not appear after a server change.	Reconnect or reload the server and check whether the server advertises listChanged and emits the list_changed notification.	A fresh tools/list response includes the changed tool set and the client refreshes its view.	Emit the list-change notification for dynamic updates, or explicitly reconnect/reload after rebuilding a server that does not emit it.
8. Tool selection	The tool is visible but the model never calls it.	Use an explicit request that clearly needs the tool, then review the tool name, description, input schema, permissions, and any on-demand tool-search behavior.	The client can select and invoke the tool with valid arguments when the request clearly matches its purpose.	Clarify the tool name and description, fix required schema fields, approve invocation, or load the deferred tool; do not misdiagnose selection as discovery failure.

Evidence reviewed

Fix an MCP server that is missing, connected with zero tools, stale, filtered, or visible but never called across Claude Code, Cursor, GitHub Copilot, and other clients. Evidence reviewed for this interactive mcp troubleshooting guide: MCP Inspector; MCP debugging guide; MCP tools specification. Decision scope: Diagnose why an MCP server is not showing tools and identify the first failing layer without widening permissions or reinstalling everything. Product behavior after Jul 19, 2026 and any benchmark result not shown on this page remain unverified.

Best next step

Apply least-privilege controls after tool discovery works. A visible tool is not automatically a safe tool; review authentication, permissions, secrets, logging, and revocation before rollout.

Methodology and disclosure

KyenAI writes this guide as an independent editorial reference, not as an endorsement page for any third-party tool. The comparison, checklist, or workflow advice is based on visible source material from MCP, Anthropic, GitHub, plus the operational constraints named on the page. Product behavior, pricing, availability, and enterprise controls can change after the listed update date, so vendor-specific claims should be rechecked against the linked sources before procurement, migration, or production rollout.

Connected with zero tools has a specific meaning

A connected state proves only that the client reached the server. It does not prove the server completed capability negotiation or returned a non-empty tool list. Claude Code's official MCP documentation explicitly distinguishes a server that advertises the tools capability but exposes no tools, and its /mcp panel shows the tool count beside each server.

Use MCP Inspector as the client-independent boundary. Its Tools tab lists tool names, descriptions, and schemas and can invoke them with test inputs. If that view is empty, fix the server implementation or registration. If it is populated, move to the target client's filters, scope, authentication, cache, and session behavior.

Test initialize before blaming tools/list

MCP tool discovery happens after the protocol initialization exchange. Verify the negotiated protocol version, the server's declared capabilities, and the initialized notification before investigating tool schemas. A transport that opens and then fails initialization can look like an empty tool catalog in a client UI.

For local stdio servers, run the exact configured command with the same arguments and environment. Use absolute paths where the working directory may differ, and write diagnostics to stderr because stdout is reserved for protocol messages. For Streamable HTTP, inspect authentication, response status, session headers, and server-side logs.

Separate discovery, loading, and invocation

Discovery asks whether tools/list returns valid tool definitions. Loading asks whether the client makes those definitions available in the current workspace, agent, and session. Invocation asks whether the model selects an available tool and receives permission to call it. Each layer has different proof and a different fix.

Claude Code and GitHub Copilot can load tools on demand to reduce context use. That means a tool may not be expanded into the model context until a matching task triggers tool search. Check the client status and tool policy before treating deferred loading as server failure.

Client-specific checks after Inspector passes

In Claude Code, use /mcp to inspect connection state, authentication, and tool count. Project-scoped configuration may require approval, duplicate names can resolve by scope precedence, and tool search can defer definitions. In GitHub Copilot CLI, inspect /mcp or copilot mcp get, then check enabled-tool filters and any custom-agent tool policy.

In Cursor or another MCP client, use the MCP settings and logs exposed by the installed version, then compare that client view with the same server in Inspector. Product interfaces and policy controls change, so retain the client version and a sanitized status capture in the bug report instead of assuming one universal menu path.

What evidence to collect before filing a bug

Record the client and server versions, transport, operating system, active config scope, exact symptom, expected tool names, initialization result, tools/list result, enabled-tool policy, and sanitized logs. Remove credentials, tokens, private URLs, and sensitive payloads before sharing any record.

The downloadable worksheet on this page follows the same eight-layer order as the debugger. Attach the first failing check and its observable output; a report that says only 'tools are missing' forces maintainers to repeat every layer.

Recommended play

Use MCP Inspector first when the server connects but exposes zero tools; it separates server discovery from client behavior.
Keep discovery, client loading, and model invocation as three different states with separate pass conditions.
Change only the first failing layer, then rerun the same proof before modifying permissions or unrelated configuration.

MCP missing-tools symptom map

Start at the row that matches the observable symptom, then move only after its pass condition is proven.

Area	Likely layer	First proof	Do not confuse with
Server absent from status	Config load or scope	Server name appears in the active client status view	A tools/list implementation bug
Configured but disconnected	Process, transport, auth, or initialization	Exact command stays alive or HTTP connection initializes	A model tool-selection problem
Connected with 0 tools	Capability negotiation or tools/list	Inspector Tools tab returns expected definitions	Write permission or prompt wording
Inspector passes, client empty	Client scope, authentication, or tool filter	Tool is enabled for the current workspace and agent	A server reinstall
Tool visible but unused	Deferred loading, description, schema, prompt, or approval	Explicit matching request selects and invokes the tool	A discovery failure

Execution steps

Capture the exact state

Record whether the server is absent, disconnected, connected with zero tools, populated only in Inspector, stale after a change, or visible but never called.

Prove process and initialization

Reproduce the exact transport, inspect initialization and declared capabilities, and eliminate stdout noise for local stdio servers.

Inspect tools/list independently

Connect MCP Inspector to the same server and verify expected names, descriptions, input schemas, and one safe test invocation.

Audit client policy

Check authentication, configuration precedence, workspace scope, enabled tools, allowlists, denylists, custom-agent policy, and on-demand loading.

Retest one changed layer

Reconnect or reload as required, repeat the original proof, and retain sanitized evidence for the server and client versions tested.

Common pitfalls

Reinstalling before finding the failing layer

A reinstall changes many variables without proving the cause. Test config, transport, initialize, and tools/list in order.

Writing debug logs to stdout

For stdio servers, keep stdout exclusively for protocol traffic and send diagnostic logs to stderr.

Treating a tool that is not called as a missing tool

First prove the tool is visible. Then check deferred loading, prompt fit, description, schema, permission, and invocation separately.

Widening every tool permission

Enable only the expected tool in the required scope. A broad allow-all rule hides policy mistakes and increases risk.

Implementation checklist

Record the exact missing-tools symptom before changing configuration.
Confirm the active config source, scope, server name, command or URL, and authentication state.
Run the exact stdio command or inspect the Streamable HTTP connection and server logs.
Verify initialization, protocol version, declared tools capability, and initialized notification.
Inspect tools/list in MCP Inspector and validate names, descriptions, and input schemas.
Check client allowlists, denylists, enabled-tool filters, workspace scope, and custom-agent policy.
Reconnect or reload after changes and verify dynamic list-change behavior where applicable.
Test one explicit, safe request that clearly matches the expected tool.
Redact credentials, tokens, private URLs, and sensitive payloads from shared evidence.

Questions this guide answers

Why is my MCP server connected but showing zero tools?

A connected state proves the transport reached the server, not that initialization completed or tools/list returned definitions. Open the same server in MCP Inspector. If its Tools tab is empty, fix capability negotiation, tool registration, tools/list, or invalid schemas. If Inspector lists tools, check the target client's scope, authentication, enabled-tool filters, and refresh behavior.

How do I test MCP tools/list?

Connect the server with the official MCP Inspector and open its Tools tab. Confirm the expected names, descriptions, and input schemas appear, then run one safe test call. This gives client-independent proof before you troubleshoot Claude Code, Cursor, GitHub Copilot, or another client's policy and loading behavior.

Why is an MCP tool visible but never called?

That is usually a selection, loading, permission, or schema problem rather than discovery failure. Use an explicit request that clearly requires the tool, check whether the client defers tools through tool search, review the description and required schema fields, and confirm the invocation is allowed in the current agent and workspace.

Should an MCP stdio server write logs to stdout?

No. For a stdio MCP server, stdout carries protocol messages, so debug output can corrupt JSON-RPC framing. Send diagnostic logs to stderr, run the exact configured command with the same environment, and use absolute paths when the client may launch from a different working directory.