Your MCP server won’t connect:

Error: Connection refused on port 3000

Or Claude Code cannot find your MCP tools. Here is how to fix it.

Fix 1: Check if server is running

# Check if port is in use
lsof -i :3000  # macOS
netstat -tlnp | grep 3000  # Linux

# Check if process is running
ps aux | grep mcp

If the server is not running, start it:

# Start MCP server
node server.js

# Or with npm
npm start

Fix 2: Fix port conflicts

Another process may be using the port:

# Find what's using port 3000
lsof -i :3000

# Kill the process
kill -9 <PID>

# Or use a different port
PORT=3001 node server.js

Fix 3: Check MCP configuration

Claude Code MCP config is in ~/.claude/mcp.json:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["./server.js"],
      "env": {
        "PORT": "3000"
      }
    }
  }
}

Verify the path and command are correct.

Fix 4: Fix tool registration

MCP servers must register tools properly:

// Server must implement tools/list
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: "my-tool",
        description: "Does something useful",
        inputSchema: {
          type: "object",
          properties: {
            query: { type: "string" }
          }
        }
      }
    ]
  };
});

Fix 5: Check environment variables

MCP servers often need API keys:

# Set in MCP config
{
  "mcpServers": {
    "github": {
      "command": "node",
      "args": ["./github-server.js"],
      "env": {
        "GITHUB_TOKEN": "ghp_..."
      }
    }
  }
}

Fix 6: Fix network issues

If server is remote:

# Check network connectivity
ping server-hostname

# Check firewall
sudo ufw status  # Linux
# Or check Windows Firewall

# Test with curl
curl http://localhost:3000/health

Fix 7: Restart Claude Code

After fixing the server, restart Claude Code:

# Exit Claude Code
/exit

# Restart
claude

Claude Code loads MCP servers on startup.

Still not working?

1. Check server logs — Look for errors in the MCP server output
2. Test with curl — Verify the server responds to HTTP requests
3. Check MCP SDK version — Update to latest: npm update @modelcontextprotocol/sdk
4. Use MCP Hub — Find working MCP servers at MCP Hub

FAQ

What port does MCP server use?

MCP servers can use any port. The default varies by server. Check your MCP server documentation or look at the port setting in your configuration. Common ports are 3000, 8080, or 5000.

How do I test if my MCP server is working?

Use curl http://localhost:PORT/health to test if the server responds. You can also check the MCP server logs for errors. If the server starts but Claude Code cannot connect, the issue is likely in the configuration.

Can I run multiple MCP servers?

Yes. Each server runs on a different port and is configured separately in your MCP config. Claude Code can connect to multiple servers simultaneously.

Related: MCP Complete Developer Guide · What is MCP? · Best MCP Servers 2026 · Claude Code MCP Setup · Claude Code Complete Guide