Claude Code silently drops all tools due to MCP SDK 1.26.0 fields (instructions, annotations, execution)

[greenstevester]

Description

XcodeBuildMCP v2.0.7 tools are completely invisible in Claude Code 2.1.39 despite the server showing as "Connected" in claude mcp list. Zero tools appear — no error, no warning.

This is caused by fields added by @modelcontextprotocol/sdk v1.26.0 that Claude Code's MCP client doesn't handle gracefully.

Affected Fields

In initialize response:

• instructions — large documentation string (~1500 chars)
• capabilities.tools.listChanged: true
• capabilities.resources and capabilities.logging

In tools/list response (per-tool):

• execution: { taskSupport: "forbidden" }
• annotations: { title: "...", readOnlyHint: true/false }
• inputSchema.$schema: "http://json-schema.org/draft-07/schema#"

How We Diagnosed

1. Created a minimal canary MCP server with bare {name, description, inputSchema} and capabilities: {tools: {}} — tools loaded ✅
2. XcodeBuildMCP proxy stripping only tool-level fields — still dropped ❌
3. Proxy also normalizing the initialize response (removing instructions, simplifying capabilities) — tools loaded ✅

The instructions field and/or extra capabilities in the initialize response appear to be the primary trigger. Tool-level annotations and execution may also contribute.

Workaround

Node.js proxy that normalizes MCP responses:

#!/usr/bin/env node
const { spawn } = require('child_process');

const proc = spawn('xcodebuildmcp', ['mcp'], {
  stdio: ['pipe', 'pipe', process.stderr],
  cwd: process.env.XCODEBUILDMCP_CWD || process.cwd(),
});

let buffer = '';
proc.stdout.on('data', (data) => {
  buffer += data.toString();
  const lines = buffer.split('\n');
  buffer = lines.pop();
  for (const line of lines) {
    if (!line.trim()) { process.stdout.write('\n'); continue; }
    try {
      const msg = JSON.parse(line);
      // Clean initialize response
      if (msg.result && msg.result.protocolVersion) {
        delete msg.result.instructions;
        if (msg.result.capabilities) {
          msg.result.capabilities = { tools: {} };
        }
      }
      // Clean tools/list response
      if (msg.result && msg.result.tools && Array.isArray(msg.result.tools)) {
        msg.result.tools = msg.result.tools.map(tool => {
          const { execution, annotations, ...rest } = tool;
          if (rest.inputSchema) delete rest.inputSchema['$schema'];
          return rest;
        });
      }
      process.stdout.write(JSON.stringify(msg) + '\n');
    } catch (e) {
      process.stdout.write(line + '\n');
    }
  }
});

process.stdin.pipe(proc.stdin);
proc.on('exit', (code) => process.exit(code || 0));
process.on('SIGTERM', () => proc.kill('SIGTERM'));
process.on('SIGINT', () => proc.kill('SIGINT'));

Save as a proxy script, then in .mcp.json:

{
  "XcodeBuildMCP": {
    "type": "stdio",
    "command": "node",
    "args": ["/path/to/xcodebuildmcp-proxy.js"],
    "env": { "XCODEBUILDMCP_CWD": "/path/to/your/project" }
  }
}

Suggested Fix

Consider one or more of:

1. Make instructions opt-in via config (e.g. enableInstructions: false in .xcodebuildmcp/config.yaml)
2. Strip instructions from initialize when the client doesn't advertise support
3. Make annotations and execution optional per MCP spec — only include them if the client negotiates support during initialize

Related

• Claude Code issue: [BUG] MCP client silently drops all tools when third-party server includes outputSchema in tools/list response anthropics/claude-code#25081
• Issue MCP server fails to connect in Claude Code despite working correctly from CLI #210 in this repo (connection failures — may be same root cause)

Environment

• XcodeBuildMCP: 2.0.7
• @modelcontextprotocol/sdk: 1.26.0
• Claude Code: 2.1.39
• macOS: Darwin 24.6.0 (Apple Silicon)

[greenstevester]

Related finding: even without the SDK v1.26.0 fields, XcodeBuildMCP tools can silently fail to load due to startup latency alone. See #210 for the full isolation test.

Our proxy workaround solves both issues simultaneously — it caches clean tool definitions (stripped of annotations/execution) AND responds instantly to the handshake, bypassing both the timeout and the schema incompatibility.

[cameroncooke]

@greenstevester I'm currently investigating so far haven't been able to repro.

[cameroncooke]

Thanks for the report. We retested with the same tool versions on our side (Claude Code 2.1.39 + xcodebuildmcp 2.0.7 resolving MCP SDK 1.26.0) and we were not able to reproduce the “connected but zero tools” behavior.

Could you share a bit more detail so we can isolate what differs?

1. The exact MCP config entry you’re using for XcodeBuildMCP.
2. Output of claude mcp get XcodeBuildMCP.
3. A debug log from one failing run (for example via claude --debug-file <path>), especially lines around MCP connect and tool discovery.
4. Whether this still reproduces with a minimal strict config (--strict-mcp-config) containing only XcodeBuildMCP.

With those, we should be able to narrow this down quickly.

[greenstevester]

Hey @cameroncooke — here's the debug info you requested:

Claude Code version: 2.1.47

MCP config entry (from project .mcp.json — this is the original config that produces zero tools):

We originally had XcodeBuildMCP configured as:

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "npx",
      "args": ["xcodebuildmcp@latest", "mcp"]
    }
  }
}

This consistently showed ✓ Connected but loaded 0 tools. The initialize → tools/list handshake timed out due to npx resolution + Rust binary cold start (~3-8s).

Current workaround: We built a Node.js proxy (xcodebuildmcp-proxy.js) that responds instantly to initialize and tools/list from a cached tool definitions file (33 tools from v2.0.7), forwarding tools/call to the real backend. This proxy is registered as a separate MCP server (xbmcp-proxy).

Proxy is still required as of today (2026-02-19) with Claude Code 2.1.47 and xcodebuildmcp 2.0.7.

Additional notes:

• macOS Darwin 24.6.0, Apple Silicon (arm64)
• The issue is specifically the MCP handshake timeout — Claude Code drops the server if tools/list doesn't respond within its timeout window
• Happy to test a fix branch if you have one available

Let me know if you need the debug log output (claude --debug-file) or the claude mcp get XcodeBuildMCP output — happy to provide.

[greenstevester]

Update: Still reproducing with XcodeBuildMCP 2.1.0 + Claude Code 2.1.68

Hey @cameroncooke — wanted to follow up. The proxy workaround is still required as of today (2026-03-05) with the latest versions:

Component	Version
XcodeBuildMCP	2.1.0 (latest)
Claude Code	2.1.68
macOS	Darwin 24.6.0 (arm64, Apple Silicon)
Node.js	v23.10.0

What still happens

1. Configure XcodeBuildMCP directly: "command": "npx", "args": ["xcodebuildmcp@latest", "mcp"]
2. Start Claude Code session
3. Server shows ✓ Connected — but 0 tools load
4. All tool calls (tap, snapshot_ui, screenshot, etc.) fail with "tool not found"
5. No error, no warning — completely silent

How to reproduce (quick test)

The fastest way to reproduce is to time the initialize → tools/list round-trip:

# This script measures how long XcodeBuildMCP takes to respond to tools/list
python3 -c "
import subprocess, json, time

proc = subprocess.Popen(
    ['npx', '-y', 'xcodebuildmcp@latest', 'mcp'],
    stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True
)

# Send initialize
start = time.time()
proc.stdin.write(json.dumps({
    'jsonrpc': '2.0', 'method': 'initialize', 'id': 0,
    'params': {
        'protocolVersion': '2024-11-05',
        'capabilities': {},
        'clientInfo': {'name': 'test', 'version': '1.0'}
    }
}) + '\n')
proc.stdin.flush()
time.sleep(2)

# Send tools/list
proc.stdin.write(json.dumps({'jsonrpc': '2.0', 'method': 'tools/list', 'id': 1}) + '\n')
proc.stdin.flush()
time.sleep(5)
proc.terminate()

elapsed = time.time() - start
output = proc.stdout.read()
for line in output.split('\n'):
    if '\"id\":1' in line:
        tools = json.loads(line)['result']['tools']
        print(f'Tools returned: {len(tools)}')
        print(f'Total time: {elapsed:.1f}s')
        break
else:
    print(f'No tools/list response after {elapsed:.1f}s')
"

On our machine this takes 3-8 seconds (npx resolution + Rust binary cold start + SDK/Xcode discovery). Claude Code's MCP handshake window is shorter than this, so tools are silently dropped.

Our proxy workaround (battle-tested over 3 weeks)

We've been using this proxy daily for E2E testing (100+ triage test scenarios via snapshot_ui, tap, type_text, gesture, etc.) and it's been rock solid.

How it works:

1. Responds instantly to initialize and tools/list from a cached JSON file (34 tool definitions)
2. Lazily spawns the real XcodeBuildMCP backend on first tools/call
3. Queues any tools/call requests that arrive before the backend is ready
4. Forwards all tools/call, resources/list, resources/read to the real backend

The proxy script (xcodebuildmcp-proxy.js):

#!/usr/bin/env node
const { spawn } = require("child_process");
const fs = require("fs");
const path = require("path");
const readline = require("readline");

// Point these at your XcodeBuildMCP install
const BACKEND_CMD = "xcodebuildmcp";  // or full path
const BACKEND_ARGS = ["mcp"];
const CACHE_PATH = path.join(__dirname, "xbmcp-tools-cache.json");

let cachedTools;
try {
  cachedTools = JSON.parse(fs.readFileSync(CACHE_PATH, "utf8"));
} catch (e) {
  process.stderr.write(`[proxy] FATAL: Cannot read tool cache: ${CACHE_PATH}\n`);
  process.exit(1);
}

let backend = null, backendReady = false, pendingCalls = [];
let backendResponseHandlers = new Map(), nextBackendId = 1000;

function ensureBackend() {
  if (backend) return;
  backend = spawn(BACKEND_CMD, BACKEND_ARGS, {
    stdio: ["pipe", "pipe", "pipe"],
    cwd: process.env.XBMCP_PROJECT_ROOT || process.cwd(),
  });
  const rl2 = readline.createInterface({ input: backend.stdout });
  rl2.on("line", (line) => {
    try {
      const msg = JSON.parse(line);
      if (msg.id !== undefined && backendResponseHandlers.has(msg.id)) {
        backendResponseHandlers.get(msg.id)(msg);
        backendResponseHandlers.delete(msg.id);
      }
    } catch {}
  });
  backend.stderr.on("data", (d) => process.stderr.write(`[backend] ${d}`));
  backend.on("exit", () => { backend = null; backendReady = false; });

  const initId = nextBackendId++;
  backendResponseHandlers.set(initId, () => {
    backend.stdin.write(JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }) + "\n");
    backendReady = true;
    for (const p of pendingCalls) forwardToBackend(p.req, p.resolve);
    pendingCalls = [];
  });
  backend.stdin.write(JSON.stringify({
    jsonrpc: "2.0", id: initId, method: "initialize",
    params: { protocolVersion: "2024-11-05", capabilities: {},
              clientInfo: { name: "xbmcp-proxy", version: "1.0.0" } },
  }) + "\n");
}

function forwardToBackend(req, respond) {
  const id = nextBackendId++;
  backendResponseHandlers.set(id, (msg) => {
    respond({ jsonrpc: "2.0", id: req.id, result: msg.result, error: msg.error });
  });
  backend.stdin.write(JSON.stringify({ ...req, id }) + "\n");
}

function callTool(req, respond) {
  ensureBackend();
  backendReady ? forwardToBackend(req, respond) : pendingCalls.push({ req, resolve: respond });
}

const rl = readline.createInterface({ input: process.stdin });
rl.on("line", (line) => {
  let req;
  try { req = JSON.parse(line); } catch { return; }
  const respond = (msg) => process.stdout.write(JSON.stringify(msg) + "\n");

  if (req.method === "initialize") {
    respond({ jsonrpc: "2.0", id: req.id, result: {
      protocolVersion: "2024-11-05",
      capabilities: { tools: { listChanged: false } },
      serverInfo: { name: "XcodeBuildMCP", version: "2.1.0-proxy" },
    }});
    ensureBackend(); // pre-warm
    return;
  }
  if (req.method === "notifications/initialized") return;
  if (req.method === "tools/list") {
    respond({ jsonrpc: "2.0", id: req.id, result: cachedTools });
    return;
  }
  callTool(req, respond); // tools/call, resources/*, everything else
});

rl.on("close", () => { if (backend) backend.kill(); process.exit(0); });
process.on("SIGTERM", () => { if (backend) backend.kill(); process.exit(0); });

Generate the tool cache (one-time, run after installing/updating XcodeBuildMCP):

python3 -c "
import subprocess, json, time
proc = subprocess.Popen(['xcodebuildmcp', 'mcp'],
    stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
proc.stdin.write(json.dumps({'jsonrpc':'2.0','method':'initialize','params':{
    'protocolVersion':'2024-11-05','capabilities':{},
    'clientInfo':{'name':'cache-gen','version':'1.0'}},'id':0}) + '\n')
proc.stdin.flush(); time.sleep(3)
proc.stdin.write(json.dumps({'jsonrpc':'2.0','method':'tools/list','id':1}) + '\n')
proc.stdin.flush(); time.sleep(5); proc.terminate()
for line in proc.stdout.read().split('\n'):
    if '\"id\":1' in line:
        result = json.loads(line)['result']
        # Strip fields that cause issues
        for t in result.get('tools', []):
            t.pop('execution', None)
            t.pop('annotations', None)
            if 'inputSchema' in t:
                t['inputSchema'].pop('\$schema', None)
        with open('xbmcp-tools-cache.json', 'w') as f:
            json.dump(result, f, indent=2)
        print(f'Cached {len(result[\"tools\"])} tools')
        break
"

MCP config (.mcp.json):

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "node",
      "args": ["/path/to/xcodebuildmcp-proxy.js"],
      "env": {
        "XBMCP_PROJECT_ROOT": "/path/to/your/project"
      }
    }
  }
}

Root cause (our theory)

Two compounding issues:

1. Startup latency: npx resolution + Rust binary cold start + SDK/Xcode discovery takes 3-8s, exceeding Claude Code's MCP handshake timeout
2. MCP SDK v1.26.0 fields: instructions in initialize response + annotations/execution on tools may further confuse Claude Code's client (see original issue description)

The proxy fixes both — instant handshake with clean responses, real backend spawned lazily.

Suggestion

Would it be feasible to add a built-in "fast start" mode to XcodeBuildMCP that defers Xcode SDK discovery until the first tools/call? That way the initialize → tools/list handshake could complete instantly with the known tool definitions, similar to what our proxy does.

Happy to help test any fix. This is a great tool — just needs to survive Claude Code's tight handshake window! 🙏

[cameroncooke]

Thanks for the detailed follow-up and for sharing your workaround.

I re-ran this end-to-end and want to clarify a few points with concrete data:

1. The posted timing script does not measure handshake latency.
   It always includes fixed sleep(2) + sleep(5) before printing elapsed time. That reported “Total time” is wall-clock time including those sleeps, not initialize -> tools/list round-trip latency.

2. “Rust binary cold start” does not match XcodeBuildMCP’s runtime path.
   XcodeBuildMCP is Node-based in this repo/package path (npx -> node).

3. We already shipped the startup-path change in #223 (merged 2026-02-15):
   MCP xcode-ide integration moved to gateway tools (xcode_ide_list_tools, xcode_ide_call_tool) so startup no longer blocks on bridge tool discovery.

Retest results (2026-03-05)

Using a response-driven harness (waits for actual JSON-RPC replies):

• npx -y xcodebuildmcp@latest mcp
  • start -> tools/list response: ~0.9–1.3s
  • tools/list request -> response: ~2–3ms

With xcode-ide explicitly enabled:

• xcode-ide: ~1.45s start -> tools/list
• session-management,simulator,xcode-ide: ~1.18s
• xcode-ide,simulator,project-discovery,ui-automation: ~0.99s
• tools/list request -> response remained ~2–3ms

The original issue reported was reproducible, but is no longer reproducible post-fix. Also the script you've provided and references to Rust are suspicious.

If you still hit “connected but 0 tools,” please share a failing claude --debug-file ... log around MCP connect and tool discovery, and we’ll continue from that trace.

Also can you confirm your machine specs as well?

[cameroncooke]

Here is the script we used to benchmark time to tools/list (including initalisation):

python3 - <<'PY'
import subprocess, json, time, threading, queue

CMD = ['npx', '-y', 'xcodebuildmcp@latest', 'mcp']
TRIALS = 5

def run_trial(i):
    proc = subprocess.Popen(
        CMD,
        stdin=subprocess.PIPE,
        stdout=subprocess.PIPE,
        stderr=subprocess.PIPE,
        text=True,
        bufsize=1,
    )
    q = queue.Queue()

    def reader():
        for line in proc.stdout:
            q.put(line.rstrip('\n'))

    threading.Thread(target=reader, daemon=True).start()

    t0 = time.time()
    proc.stdin.write(json.dumps({
        'jsonrpc': '2.0',
        'id': 0,
        'method': 'initialize',
        'params': {
            'protocolVersion': '2024-11-05',
            'capabilities': {},
            'clientInfo': {'name': 'latency-harness', 'version': '1.0'}
        }
    }) + '\n')
    proc.stdin.flush()

    init_ok = False
    while time.time() - t0 < 30:
        try:
            msg = json.loads(q.get(timeout=0.1))
        except Exception:
            continue
        if msg.get('id') == 0:
            init_ok = True
            break

    proc.stdin.write(json.dumps({'jsonrpc': '2.0', 'method': 'notifications/initialized'}) + '\n')
    proc.stdin.flush()

    t_list = time.time()
    proc.stdin.write(json.dumps({'jsonrpc': '2.0', 'id': 1, 'method': 'tools/list'}) + '\n')
    proc.stdin.flush()

    got_list = False
    tool_count = None
    while time.time() - t0 < 30:
        try:
            msg = json.loads(q.get(timeout=0.1))
        except Exception:
            continue
        if msg.get('id') == 1:
            got_list = True
            tool_count = len((msg.get('result') or {}).get('tools', []))
            break

    t1 = time.time()

    proc.terminate()
    try:
        proc.wait(timeout=3)
    except subprocess.TimeoutExpired:
        proc.kill()

    print({
        'trial': i,
        'init_ok': init_ok,
        'got_tools_list': got_list,
        'tool_count': tool_count,
        'start_to_tools_list_response_s': round(t1 - t0, 3),
        'tools_list_req_to_resp_s': round(t1 - t_list, 3),
    })

for i in range(1, TRIALS + 1):
    run_trial(i)
PY

To run just paste into terminal, you'll need python3 installed and npx.

[cameroncooke]

@greenstevester Thanks again for the detailed reports and repro work. I re-verified this triage against the current code and release history:

• The startup-path/handshake work landed earlier and is included in v2.3.2.
• Current has the same startup architecture (plus additional follow-on improvements), and we still can’t reproduce a deterministic "connected but zero tools" failure from this issue report.

Given that status, I’m closing this as resolved in released builds (v2.3.2) rather than main-only. If you can still reproduce on current Claude Code + current XcodeBuildMCP, please open a fresh issue with:

1. exact versions,
2. MCP config,
3. debug log around /.

Happy to reopen quickly with a modern repro trace.

[cameroncooke]

@greenstevester Quick correction because my previous comment got markdown-escaped badly in the CLI submission:

• Current main has the same startup architecture (plus follow-on improvements).
• If this reproduces again, please include debug log lines around the JSON-RPC initialize and tools/list exchange so we can validate handshake timing/behavior directly.

Thanks again for the thorough investigation you shared earlier.