fix(mcp): Claude Desktop app-only config omits required command #506

Summary

The Claude Desktop section tells readers to put a remote url/headers entry in claude_desktop_config.json, then restart to see the X tools. Claude Desktop's local MCP configuration requires a command; the documented app-only entry is filtered out by its config loader. This report concerns that client-specific example, not the remote entries shown for other clients.

Runtime or environment

• X documentation: current main commit 5fcfe3da51461ef1c0b59a028da9c365547cad4c; this repository has no published releases. The live MCP guide also contains the example.
• Claude Desktop for macOS: installed build 2.42304.2 and published stable build 3.1623.1, obtained independently from Anthropic's release feed. The latter was extracted into a disposable directory for inspection; neither app was launched with a changed configuration.

Steps to reproduce

1. Read the Claude Desktop section's App-only Bearer example in tools/mcp.mdx and its instruction to edit claude_desktop_config.json.
2. Inspect each stated build's bundled app.asar, under .vite/build, and follow the local app-config schema and loader described below.
3. Compare the example's xapi object with the required local MCP server schema. Its keys are url and headers; command is absent.

These documentation and code-inspection steps were executed. The separate end-to-end step of saving this entry and restarting Claude Desktop was not executed; no real configuration was edited and no X API request was made.

Expected behavior

The client-specific instructions should use a configuration route Claude Desktop accepts and accurately describe how readers can make the X tools available. A claude_desktop_config.json example must satisfy the local MCP schema. Direct remote setup should distinguish the account-level custom connector route from the local config file and preserve any authentication availability limits.

Actual behavior

The app-only example contains:

{
  "mcpServers": {
    "xapi": {
      "url": "https://api.x.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_APP_ONLY_BEARER_TOKEN" }
    }
  }
}

In the installed build, .vite/build/index.chunk-BkhOOUzl.js defines the server schema as wg=j({command:D(),args:A(D()).optional(),env:Rn(D(),D()).optional(),extensionId:D().optional()}). The app-config schema uses mcpServers:Rn(D(),wg).optional(). Dht() reads the config file and validates it; on failure, jht() retains only entries for which wg.safeParse(entry).success is true and records the rest as invalid.

The published stable build preserves the same requirement in .vite/build/index.chunk-CG9jv6zY.js: Ig=A({command:E(),args:k(E()).optional(),env:j(E(),E()).optional(),extensionId:E().optional()}), used by Lgt as mcpServers:j(E(),Ig).optional(). Its file loader Rgt() calls Hgt() to filter invalid entries. A required command cannot be supplied by the example's url or headers, so xapi is removed from the loaded server map. Both builds contain the warning text saying invalid entries in the config file were skipped. This is static proof of the loader result, not an observed UI warning or a completed MCP handshake.

Evidence

• Expected source: the official local MCP setup guide documents Settings → Developer → Edit Config with command/args. Anthropic's remote MCP connector guide separates local JSON configuration from remote custom connectors added through Connectors. Its custom connector authentication documentation places fixed bearer credentials in the connector dialog's Request headers field and describes availability limits; this is not a headers field for the local JSON file.
• Failure source: tools/mcp.mdx, Claude Desktop section, plus the two bundled schema and file-loader paths quoted above.
• Evidence provenance: static
• Local verification: static-proof
• Reproduction completeness: complete

The concrete trigger is the documented JSON object at the documented local config-file entry point. The file loader validates the server map with the required-command schema, filters the invalid xapi entry, and returns the filtered config when it validates. No app launch or network behavior is claimed.

Restoration check

Follow the revised Claude Desktop app-only instructions and confirm they use an accepted configuration route with the required bearer authentication, while retaining read-only app-only semantics. If a local JSON example remains, verify that its server entry survives the stated config loader. If the remote connector route is documented instead, state the relevant request-header availability limits. Confirm the instructions actually make X tools available before promising that result after restart.

Triage assessment

• Impact level: P2
• Assessment status: supported
• Impact basis: The documented app-only setup produces an invalid local MCP entry that the inspected loaders filter out, preventing that entry from becoming a configured server. This is bounded to the Claude Desktop example; an end-to-end tool connection was not tested.
• Workaround status: unverified
• Workaround basis: Official documentation describes remote custom connectors and conditionally available request headers, but this investigation did not establish that the X app-only connection succeeds through that route. No bridge workaround was executed in this investigation.