[BUG]

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Bug Report: claude mcp list fails with "No available ports found" error

Description

The claude mcp list command fails with a port allocation error, preventing users from listing configured MCP servers.

Error Message

Proxy startup failed with exit code 1:
(node:26910) ExperimentalWarning: SQLite is an experimental feature and might change at any time
file:///opt/homebrew/lib/node_modules/@apple/claude-code/packages/proxy/dist/server.bundle.js:32317
  throw new Error(`No available ports found after ${maxAttempts} random attempts and sequential fallback`);
        ^

Error: No available ports found after 50 random attempts and sequential fallback
    at getAvailablePort (file:///opt/homebrew/lib/node_modules/@apple/claude-code/packages/proxy/dist/server.bundle.js:32317:9)
    at process.processTicksAndRejections (node:internal/process/task_queues:104:5)
    at async determineServerConfig (file:///opt/homebrew/lib/node_modules/@apple/claude-code/packages/proxy/dist/server.bundle.js:32339:12)
    at async file:///opt/homebrew/lib/node_modules/@apple/claude-code/packages/proxy/dist/server.bundle.js:44455:20

Node.js v24.14.0

Environment

• OS: macOS Darwin 25.2.0
• Claude Code Version: @apple/claude-code 0.0.124 (updated to latest)
• Wrapped Anthropic Version: @anthropic-ai/claude-code 2.1.5
• Node.js Version: v24.14.0
• Installation: Homebrew (/opt/homebrew/lib/node_modules/@apple/claude-code)

Steps to Reproduce

1. Run claude mcp list
2. Command fails with "No available ports found" error

Investigation Results

System Status

• Listening ports: Only 21 ports currently in use (verified with netstat -an | grep LISTEN)
• File descriptor limit: 1,048,575 (verified with ulimit -n)
• System file limits: kern.maxfiles=368,640, kern.maxfilesperproc=184,320
• Zombie processes: None found (verified with ps aux | grep mcp)

Port Binding Test

Node.js can successfully bind to ports on the system:

$ node -e "const net = require('net'); const server = net.createServer(); server.listen(0, '127.0.0.1', () => { const port = server.address().port; console.log('Successfully bound to port:', port); server.close(); });"
Successfully bound to port: 52004

This confirms the issue is specific to the Claude Code MCP proxy, not a system-level problem.

MCP Configuration

MCP servers are configured in ~/.config/claude-code/settings.json:

• 3 disabled servers (filesystem, brave-search, github)
• 1 enabled HTTP server (mcp-docs)

Troubleshooting Attempted

1. ✅ Checked for zombie MCP processes (none found)
2. ✅ Verified system has plenty of available ports
3. ✅ Verified file descriptor limits are not restrictive
4. ✅ Updated Claude Code to latest version (claude update)
5. ✅ Tested that Node.js can successfully bind to ports
6. ✅ Verified security sandbox permissions for ps and lsof commands

Analysis

The error suggests the MCP proxy is unable to find an available port despite:

• The system having minimal port usage (21 listening ports)
• High system limits (368K max files, 1M file descriptors)
• No competing MCP processes running
• Node.js being able to bind to ports successfully

This appears to be an interaction issue between the security sandbox and the MCP proxy's port allocation mechanism (getAvailablePort function).

Expected Behavior

claude mcp list should successfully list configured MCP servers without port allocation errors.

Actual Behavior

Command fails after attempting 50 port allocations with the error "No available ports found after 50 random attempts and sequential fallback".

Impact

Users cannot:

• List configured MCP servers
• Verify MCP server status
• Troubleshoot MCP configuration issues

Workaround

Currently, users can view MCP server configuration by directly reading:

cat ~/.config/claude-code/settings.json

Additional Context

The error occurs consistently even after:

• System restart
• Claude Code update
• Security sandbox permission changes
• Clearing temporary files

What Should Happen?

See above report - all info contained above

Error Messages/Logs

Steps to Reproduce

Claude map-setup

Claude Model

None

Is this a regression?

Yes, this worked in a previous version

Last Working Version

_No response_

Claude Code Version

0.0.124

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

_No response_