MCP tool descriptor files (tools/*.json) not written on initial server connection

Support Bug Reports
1

Describe the Bug

When a Cursor window first connects to an MCP server, the mcps// directory under ~/.cursor/projects// is created with INSTRUCTIONS.md and SERVER_METADATA.json, but the tools/ subdirectory containing the per-tool JSON descriptor files is not created. This means agents following the documented workflow of reading tool schemas before calling MCP tools find no schemas to read.

Toggling the MCP server off and back on in Cursor Settings > MCP reliably fixes the issue – after the toggle, the tools/ directory appears with all descriptor files.

Steps to Reproduce

  1. Open a workspace that has an MCP server configured (in this case, a custom MCP server with 64 tools).
  2. Wait for the MCP server to connect (green status indicator in settings).
  3. Check the MCP descriptor directory: ls ~/.cursor/projects/<workspace-slug>/mcps/<server-id>/
  4. Observe that only INSTRUCTIONS.md and SERVER_METADATA.json are present – no tools/ subdirectory.
  5. Toggle the MCP server off and back on in Cursor Settings > MCP.
  6. Re-check the same directory.
  7. The tools/ subdirectory now exists with all 64 .json descriptor files.

Expected Behavior

The tools/ directory with all tool descriptor JSON files should be written during the initial MCP server connection, at the same time as INSTRUCTIONS.md and SERVER_METADATA.json. Agents rely on these descriptors to discover tool parameter schemas before making MCP calls, per the system prompt guidance: “browse the MCP tool descriptors in the file system to understand what tools are available.”

Operating System

Windows 10/11

Version Information

Version: 2.6.21 (user setup)
VSCode Version: 1.105.1
Commit: fea2f546c979a0a4ad1deab23552a43568807590
Date: 2026-03-21T22:09:10.098Z
Build Type: Stable
Release Track: Default
Electron: 39.8.1
Chromium: 142.0.7444.265
Node.js: 22.22.1
V8: 14.2.231.22-electron.0
OS: Windows_NT x64 10.0.26100

Additional Information

  • The MCP server in question exposes 64 tools via the FastMCP framework.
  • A second Cursor workspace window connected to the same MCP server 3 days earlier does have the tools/ directory populated from its initial connection, suggesting this is a race condition rather than a deterministic failure.
  • Both cursor-ide-browser and the custom MCP server were affected in the same session – neither had a tools/ directory until the toggle.
  • Timestamps confirm the metadata files and the (missing) tools directory share the same creation time after the toggle, suggesting they are written in the same operation – but the initial connect only wrote the metadata files.
  • This may be a race condition where the MCP handshake completes and metadata is written before tool enumeration finishes, and the deferred tool-write step is dropped.

Does this stop you from using Cursor

No - Cursor works, but with this issue

5

Hey, thanks for the detailed report. This is a known issue. It’s a race condition where the tool descriptors don’t get written on the first connection because the tools cache is still empty at the moment of the first write.

A similar thread was here: MCP tool schemas not populated to file system MCP tool schemas not populated to file system for Agent context - Agent cannot discover available tools. One user confirmed a fix in a newer version, but another said the issue came back. So it looks like a regression.

For now, the only reliable workaround is toggling it off and on, like you already found.

The team is aware of this problem. Your report helps with prioritization, and it’s especially helpful that you captured a clear pattern 64-tool FastMCP, Windows, and metadata timestamps. I’ll update here when there’s news.