# MCP tool descriptor files (tools/\*.json) not written on initial server connection **URL:** \ **Category:** Bug Reports\ **Tags:** mcp\ **Created:** [March 26, 2026, 2:51pm UTC](https://forum.cursor.com/t/mcp-tool-descriptor-files-tools-json-not-written-on-initial-server-connection/155950 "2026-03-26T14:51:37Z")\ **Posts on this page:** 4\ **Page:** 1
**Author:** ![CHeelan](https://avatars.discourse-cdn.com/v4/letter/c/df788c/32.png) [@CHeelan](https://forum.cursor.com/u/CHeelan)\ **Post date:** [March 26, 2026, 2:51pm UTC](https://forum.cursor.com/t/mcp-tool-descriptor-files-tools-json-not-written-on-initial-server-connection/155950/1 "2026-03-26T14:51:37Z")
### 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//mcps//` 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 ---
**Author:** ![deanrie](https://sea3.discourse-cdn.com/cursor1/user_avatar/forum.cursor.com/deanrie/32/1263_2.png) [@deanrie](https://forum.cursor.com/u/deanrie)\ **Post date:** [March 26, 2026, 3:56pm UTC](https://forum.cursor.com/t/mcp-tool-descriptor-files-tools-json-not-written-on-initial-server-connection/155950/5 "2026-03-26T15:56:56Z")
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](https://forum.cursor.com/t/mcp-tool-schemas-not-populated-to-file-system-for-agent-context-agent-cannot-discover-available-tools/150787). 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. ---
**Author:** ![mohitjain](https://sea3.discourse-cdn.com/cursor1/user_avatar/forum.cursor.com/mohitjain/32/100229_2.png) [@mohitjain](https://forum.cursor.com/u/mohitjain)\ **Post date:** [April 7, 2026, 9:59am UTC](https://forum.cursor.com/t/mcp-tool-descriptor-files-tools-json-not-written-on-initial-server-connection/155950/8 "2026-04-07T09:59:31Z")
Hey @CHeelan! The MCP tool descriptor discovery issue has been addressed in a recent Cursor update. Updating to the latest version should resolve this. ---
**Author:** ![system](https://sea3.discourse-cdn.com/cursor1/user_avatar/forum.cursor.com/system/32/99069_2.png) [@system](https://forum.cursor.com/u/system)\ **Post date:** [April 29, 2026, 9:59am UTC](https://forum.cursor.com/t/mcp-tool-descriptor-files-tools-json-not-written-on-initial-server-connection/155950/9 "2026-04-29T09:59:51Z")
This topic was automatically closed 22 days after the last reply. New replies are no longer allowed.