Client Issues

Problems with MCP client detection, configuration, and connectivity.

No Clients Detected

"No MCP clients detected on this system"

Cause: The setup wizard couldn't find any supported MCP clients.

Fix:

1. Install a supported MCP client
2. Ensure the client has been opened at least once (to create config directories)
3. Re-run the setup wizard:

   npx @structured-world/gitlab-mcp setup

Detection Methods

Client	How Detected	Requirement
Claude Desktop	macOS app bundle	App installed
Claude Code	claude in PATH	CLI installed
Cursor	~/.cursor/ exists	Opened once
VS Code	.vscode/ exists	Project workspace
Windsurf	~/.codeium/windsurf/ exists	Opened once
Cline	Extension storage exists	Extension installed
Roo Code	~/.roo/ exists	Opened once

Config Not Loaded

Server Not Appearing in Client

Check 1: Config file path

Ensure you're editing the correct file. See Clients for paths per OS.

Check 2: JSON syntax

Validate your config file:

# macOS/Linux
python3 -m json.tool < ~/.cursor/mcp.json

# Or use jq
jq . ~/.cursor/mcp.json

Common JSON errors:

• Trailing comma after last item
• Missing quotes around keys
• Comments (JSON doesn't support comments)

Check 3: Restart required

Most clients require a full restart after config changes:

• Claude Desktop: Quit and reopen
• Cursor: Close all windows and reopen
• VS Code: "Reload Window" (Cmd+Shift+P)
• Windsurf: Restart application

Check 4: Config structure

Ensure the mcpServers key is at the root level:

{
  "mcpServers": {
    "gitlab": { ... }
  }
}

Not nested inside another object.

Already Configured

"Client already has gitlab-mcp configured"

This means an existing gitlab entry was found in the config.

Options:

1. Use --force to overwrite:

   npx @structured-world/gitlab-mcp install --cursor --force

2. Manually edit the config file to update specific values
3. A backup is created automatically when overwriting

Command Not Found

"npx: command not found"

Cause: Node.js is not installed or not in PATH.

Fix:

1. Install Node.js >= 24:

   # macOS (Homebrew)
   brew install node
   
   # Or use nvm
   nvm install 24
   nvm use 24

2. Verify: node --version and npx --version

Full Path Workaround

If npx isn't in the client's PATH, use the full path:

{
  "mcpServers": {
    "gitlab": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "@structured-world/gitlab-mcp"]
    }
  }
}

Find your npx path: which npx

Client-Specific Issues

Claude Desktop

• macOS only: Claude Desktop MCP is currently macOS-only for auto-detection
• Logs: ~/Library/Logs/Claude/mcp*.log
• Config test: Open Claude, check MCP indicator icon (bottom-left)

Cursor

• Global config: Uses ~/.cursor/mcp.json (not per-project)
• MCP panel: Settings > MCP shows connected servers
• Restart: Close ALL Cursor windows, then reopen

VS Code

• Per-project: Uses .vscode/mcp.json in workspace root
• Copilot required: MCP support needs GitHub Copilot extension
• Multi-root workspaces: Each workspace root needs its own config

Cline

• Extension required: Must have saoudrizwan.claude-dev extension installed
• Settings location: Inside VS Code extension storage
• Update path: If extension ID changes, config path changes too

Permission Issues

"EACCES: permission denied"

Cause: Cannot write to the config file.

Fix:

# Fix permissions (replace path with your config)
chmod 644 ~/.cursor/mcp.json

# Or fix directory permissions
chmod 755 ~/.cursor

Config in Protected Directory

If the config is in a system-protected location, run the install with elevated permissions or edit manually with sudo.

See Also

• Client configuration guides
• Manual Configuration
• Connection Issues