# 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.

## 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.

## 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.

## Recommended play

1. Use MCP Inspector first when the server connects but exposes zero tools; it separates server discovery from client behavior.
2. Keep discovery, client loading, and model invocation as three different states with separate pass conditions.
3. 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

1. **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.
2. **Prove process and initialization** — Reproduce the exact transport, inspect initialization and declared capabilities, and eliminate stdout noise for local stdio servers.
3. **Inspect tools/list independently** — Connect MCP Inspector to the same server and verify expected names, descriptions, input schemas, and one safe test invocation.
4. **Audit client policy** — Check authentication, configuration precedence, workspace scope, enabled tools, allowlists, denylists, custom-agent policy, and on-demand loading.
5. **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.

## FAQ

**Q: 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.

**Q: 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.

**Q: 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.

**Q: 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.

## Evidence sources

- [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) — MCP. Official client-independent tool for inspecting server connections, capabilities, tools, schemas, calls, and notifications.
- [MCP debugging guide](https://modelcontextprotocol.io/docs/tools/debugging) — MCP. Official guidance for stdio logging, paths, environment variables, initialization, transport debugging, and client logs.
- [MCP tools specification](https://modelcontextprotocol.io/specification/draft/server/tools) — MCP. Defines tool discovery, tools/list, tool schemas, and list-change capability behavior.
- [Connect Claude Code to tools via MCP](https://code.claude.com/docs/en/mcp) — Anthropic. Documents /mcp status, tool count, scope precedence, dynamic updates, reconnection, authentication, and Tool Search.
- [MCP server debugging guide](https://docs.github.com/en/copilot/how-tos/copilot-sdk/troubleshooting/mcp-debugging) — GitHub. Official debugging guidance for server startup, enabled tools, initialize, tools/list, schemas, timeouts, and stdout framing.

## Related guides

- [MCP server security checklist](/guides/secure-mcp-servers-ai-coding-agents) — After discovery works, review each visible tool's authentication, permissions, data access, logs, and revocation path.
- [Claude Code hooks and MCP setup](/guides/claude-code-hooks-mcp-setup) — Use the control map to decide whether the failing capability belongs in MCP, a hook, or a reusable skill.
- [AI agent governance checklist](/guides/agent-governance-checklist-for-software-teams) — Tool inventory, ownership, audit evidence, and approval boundaries belong in the wider governance process.
- [loop engineering verification workflow](/guides/loop-engineering-ai-coding-agents) — Turn each diagnostic layer into an observable pass or stop condition for repeatable agent operations.

---
Canonical: https://www.kyenai.com/guides/mcp-server-not-showing-tools