Blog / Developer tools

MCP Tools Not Showing? 5-Step Fix for the 2026-07-28 Spec (Oct 2026)

2026-10-18cdnping editors5 min read

If your MCP tools suddenly disappear after upgrading Claude Code or another client, suspect the protocol version first. The 2026-07-28 MCP spec is becoming the default negotiated version across clients, and an older server, or one that doesn't fully implement the new fields, may connect fine but return no tools. The fastest check is to set MCP_PROTOCOL_NEGOTIATION=legacy to fall back to the old negotiation (the changelog says this switch applies to negotiation for claude.ai connectors, cloud sessions and Remote Control connectors). If the tools come back, the problem is most likely the version. This article is written as of October 2026, and version numbers follow each project's public changelog.

#What actually changed?

The MCP official blog published the 2026-07-28 spec on July 28, 2026, and followed with a new roadmap on August 22 (see the MCP official blog). The changes relevant to troubleshooting are these (per that blog post):

• The core is now stateless: the initialize/initialized handshake and the Mcp-Session-Id header are gone. Each request carries its own protocol version, client info and capabilities.
• An optional server/discover call is added. Clients that want to learn server capabilities up front can use it, but it isn't required.
• When a server needs user input, it returns resultType: "input_required" and the client retries with the answer.
• Responses to tools/list, prompts/list, resources/list and resources/read carry ttlMs and cacheScope, so clients can decide how to cache.

The handshake is gone. The 2.1.302 fix notes explain that if a server negotiates the new version but omits these fields, the tool list can come back empty.

#What state are the clients in?

Note that the Codex entry is an OAuth capability, not a protocol version switch. Don't mix the two when troubleshooting.

#How do I troubleshoot missing tools step by step?

#Step 1: Is your client recent enough?

For Claude Code, check the version first:

claude --version

If it's below 2.1.302, upgrade. That version fixes the case where the new protocol is negotiated but fields are missing, leaving the tool list empty. If your tools vanished for no obvious reason, this may be it.

#Step 2: Which SDK version does the server use?

Check whether the official SDK your MCP server depends on (TypeScript, Python, Ruby and so on) has a release that supports 2026-07-28. If you wrote your own protocol implementation, check in particular that list responses return ttlMs and cacheScope. For the exact field requirements, go by the spec documentation.

#Step 3: Temporarily fall back to legacy negotiation

MCP_PROTOCOL_NEGOTIATION=legacy claude

This is the opt-out switch given in the Claude Code changelog. Per the changelog text, the default negotiation of the new version covers claude.ai connectors, cloud sessions and Remote Control connectors. Whether your own locally configured MCP servers are affected is something to confirm in the official docs. If tools come back, the server and the new protocol are incompatible and you should upgrade the server. Treat this as a stopgap only, and don't rely on it long term.

#Step 4: Check description length

Claude Code limits the length of MCP tool descriptions and server instructions. According to the changelog, 2.1.296 raised the default limit from 2,048 to 4,096 characters, and 2.1.300 set the truncation point for tool descriptions loaded through tool search to 16,384 characters. If a server's descriptions are too long, they may be truncated and the model sees an incomplete version. Put the core usage at the start of the description.

#Step 5: For remote MCP, confirm the network works first

After a remote MCP server disconnects, versions before 2.1.295 might never reconnect in headless and SDK sessions. To tell a network problem from a protocol problem:

1. Request the server URL directly with curl and see whether it responds.
2. Use the cdnping online speed test to check first-connection and round-trip latency from your current network to the relevant APIs.
3. For the Anthropic side, check /en/status/anthropic for anomalies.

For systematic network-layer troubleshooting, see How to troubleshoot Claude Code connection timeouts and errors: a four-layer network checklist and the Developer network self-check list (2026 edition).

#A few related questions

I use a custom API endpoint. Does this affect me? Protocol version negotiation happens between the client and the MCP server. It is separate from the model endpoint address. For endpoint configuration, see Configuring custom API endpoints for Claude Code, Codex and OpenCode.

Is the client broken, or is the provider having an outage? Separate the layers first. For how to read status pages, see How to read the OpenAI and Claude status pages.

Is Codex upgrading at the same time? Yes. Codex has also had recent version and model changes; see Codex retires its old default model on October 14, and CLI 0.163 adds mid-run follow-ups and a /config panel.

#Summary and checklist

• Upgrade the client to a recent version (Claude Code 2.1.302 at minimum).
• Upgrade the server SDK so list responses include resultType, ttlMs, cacheScope and the other new fields.
• Use MCP_PROTOCOL_NEGOTIATION=legacy as a control to confirm whether it is a version problem.
• Keep tool descriptions short, with key information first.
• For remote servers, rule out network problems first.

Note: the MCP official blog does not describe the exact version negotiation mechanism in detail. This article only cites what it states explicitly. Final client behavior is defined by each changelog and official documentation.

#Sources

• The 2026-07-28 Specification (MCP official blog, 2026-07-28)
• MCP official blog (roadmap, 2026-08-22)
• Claude Code CHANGELOG
• Devin Desktop changelog
• Codex changelog