Shadcn MCP Failed to Connect: Causes and Fixes

Quick Answer

The fastest way to diagnose a shadcn MCP connection failure:

1. Identify exactly which package or server you are running — there is no single universal "Shadcn MCP Server." Find the package name.
2. Run the exact MCP command manually in your terminal and watch stderr. The real error is almost always there.
3. Check Node.js version and PATH — GUI clients like Cursor and Claude Desktop often cannot find node or npx because they launch with a restricted PATH.
4. Separate registry failures from MCP failures — the shadcn registry at ui.shadcn.com and the MCP transport layer are two different things that fail in different ways.

If the process exits immediately: it is almost always a missing package, a PATH problem, or stdout contamination. If the process connects but tools are missing: the server initialized but tool registration failed. If you get a network error: the registry endpoint or remote server is unreachable.

Shadcn MCP Failed to Connect: 60-Second Checklist

Work through this in order. Most failures resolve in the first three steps.

• Identify the package — What is the exact npm package name or binary you are running? Confirm it exists on npm with npm info <package-name>.
• Run the command manually — Open a terminal, paste the exact command from your MCP config, and run it. Watch both stdout and stderr.
• Check Node.js version — Run node --version. Many MCP servers require Node.js 18+. Some require 20+.
• Check PATH in the client — In Cursor or Claude Desktop configs, use absolute paths: /usr/local/bin/npx not npx.
• Check args format — The args array in your client config must be a JSON array of strings, not a single string with spaces.
• Clear npx cache — Run npx --yes clear-npx-cache or delete ~/.npm/_npx.
• Verify registry access — Run curl https://ui.shadcn.com/registry/index.json to confirm registry is reachable.
• Check for stdout contamination — If the package logs anything to stdout before the JSON-RPC handshake, the MCP client will reject it.
• Restart the MCP client fully — Not just reload. Fully quit and reopen Cursor, Claude Desktop, or your IDE.
• Test with MCP Inspector — Isolate whether the server itself works before blaming the client.

Jump to the Right Fix

Step Zero: Identify Your Shadcn MCP Implementation

Before fixing anything, you need to know exactly what you are running. This matters because:

• There is no single official "Shadcn MCP Server" from the shadcn/ui team as of early 2025. The shadcn/ui project provides a CLI (shadcn) and a public registry (ui.shadcn.com), but not a first-party MCP server package.
• Community developers have built MCP servers that wrap the shadcn registry, the shadcn CLI, or both. These have different package names, different transports, different tool sets, and different failure modes.
• Some projects use the shadcn registry as a data source inside a broader MCP server.

Find your package name first:

# Check your MCP client config file
cat ~/.cursor/mcp.json
# or
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

Look at the command and args fields. The package name is usually passed as an argument to npx or node.

{
  "mcpServers": {
    "shadcn": {
      "command": "npx",
      "args": ["-y", "some-shadcn-mcp-package"],
      "env": {}
    }
  }
}

Then verify the package exists:

npm info some-shadcn-mcp-package

If npm info returns nothing or an error, the package name is wrong or the package has been unpublished. That alone explains the connection failure.

Fixing Command, Args, Runtime, and Package Problems

Wrong Package Name

Symptom: MCP client shows "failed to connect" or "spawn error" immediately.

Verify:

npm info <your-package-name> version

If this returns npm ERR! 404, the package does not exist under that name.

Fix: Find the correct package name from the server's GitHub repository or documentation. Do not guess package names.

Incorrect args Array

The args field in MCP config must be a JSON array of separate strings, not a single space-separated string.

Wrong:

{
  "command": "npx",
  "args": ["-y some-shadcn-mcp-package --port 3000"]
}

Correct:

{
  "command": "npx",
  "args": ["-y", "some-shadcn-mcp-package", "--port", "3000"]
}

This is one of the most common configuration mistakes. Each flag and value is a separate array element.

Node.js Version Incompatibility

Symptom: Server exits immediately with a syntax error or SyntaxError: Unexpected token in stderr.

Verify:

node --version
# Many shadcn-related MCP servers require Node.js 18+

Fix:

# Using nvm
nvm install 20
nvm use 20
nvm alias default 20

# Confirm the client picks up the right node
which node

Important: If you use nvm, the node binary path changes per version. GUI clients use the PATH at launch time, not your shell's current nvm version. Use the absolute path in your MCP config.

npx Cache Corruption

Symptom: npx fails with a module resolution error or installs but then crashes.

Fix:

# Clear npx cache
rm -rf ~/.npm/_npx

# Or use the npm cache clean command
npm cache clean --force

# Force fresh download
npx --yes <package-name>

Using pnpm dlx or bun x

If your project uses pnpm or bun, you can replace npx in the MCP config:

{
  "command": "/usr/local/bin/pnpm",
  "args": ["dlx", "some-shadcn-mcp-package"]
}

Get the absolute path: which pnpm or which bun. Do not use bare pnpm or bun as the command in GUI clients.

Fixing Local Stdio Startup Failures

Stdio-based MCP servers communicate over stdin/stdout. Any output on stdout before the JSON-RPC handshake breaks the protocol. This section covers the most common reasons a shadcn MCP server process exits immediately or fails to initialize.

Module Not Found

Symptom: Process exits with Error: Cannot find module '...'.

Verify:

# Run the exact command from your config manually
npx -y <package-name> 2>&1

Look for MODULE_NOT_FOUND in the output.

Fix:

# Pre-install the package globally
npm install -g <package-name>

# Or run with explicit cache directory
NPX_HOME=~/.npx npx -y <package-name>

Stdout Contamination

Symptom: Connection fails with a JSON parse error, or the client reports a protocol error. The server seems to start but never completes handshake.

How it happens: A dependency or the server itself prints a startup message, a debug log, a banner, or a deprecation warning to stdout. The MCP client reads stdout expecting pure JSON-RPC. Any other bytes cause a parse failure.

Verify:

npx -y <package-name> 2>/dev/null | head -5

If the first bytes are not {"jsonrpc":"2.0" or similar, you have stdout contamination.

Fix options:

• Check if the package accepts a --silent or --quiet flag.
• Check if you can set NODE_ENV=production to suppress verbose logging.
• If you control the server source, move all debug output to stderr, never stdout.
• Report the issue to the package maintainer — stdout contamination is a server bug.

Process Exits Immediately Without Error

Symptom: The MCP client says the server disconnected instantly. No useful error shown in the client UI.

Verify:

# Run with stderr redirected to a file so you can read it
npx -y <package-name> 2>/tmp/mcp-debug.log
cat /tmp/mcp-debug.log

Common culprits:

• Missing required environment variable
• File permission error on config or cache directory
• Incompatible dependency version
• The package entry point calls process.exit() on an unhandled condition

Working Directory Problems

Some shadcn MCP servers need to run from inside a Next.js or shadcn project directory to auto-detect components, components.json, or the registry configuration.

Fix: Add a cwd field in your MCP client config if supported:

{
  "mcpServers": {
    "shadcn": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "<package-name>"],
      "cwd": "/Users/yourname/projects/my-nextjs-app"
    }
  }
}

Not all MCP clients support cwd. Check your client's documentation.

Command Works in Terminal but Fails in MCP Client

This is the most frustrating class of failure because you can clearly see the server works — just not through your client.

The PATH Problem Explained

When you open a terminal, your shell loads .bashrc, .zshrc, or .profile and sets up PATH with nvm directories, Homebrew paths, and user-local npm bins. GUI applications like Cursor and Claude Desktop do not load your shell profile. They inherit a minimal system PATH.

Diagnose:

# What path does your shell have?
echo $PATH

# What path does a GUI-launched process have?
# On macOS, check:
/usr/libexec/path_helper

Fix — Use Absolute Paths in Config:

# Find where your node and npx actually live
which node
# Example output: /Users/you/.nvm/versions/node/v20.11.0/bin/node

which npx
# Example output: /Users/you/.nvm/versions/node/v20.11.0/bin/npx

Then put those absolute paths in your MCP config:

{
  "mcpServers": {
    "shadcn": {
      "command": "/Users/you/.nvm/versions/node/v20.11.0/bin/npx",
      "args": ["-y", "<package-name>"]
    }
  }
}

Restart the Client, Not Just Reload

Cursor and Claude Desktop cache MCP server configurations. A config change requires a full application restart, not just a settings reload.

• Cursor: Quit completely (Cmd+Q on macOS), reopen.
• Claude Desktop: Quit from the system tray or menu bar, reopen.

A "reload" or "restart MCP" button in the UI is not always equivalent to a full process restart.

Environment Variables Not Inherited

If your server needs environment variables (API keys, registry URLs, custom config paths), these must be explicitly set in the MCP config env field. The client does not inherit your shell environment.

{
  "mcpServers": {
    "shadcn": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "<package-name>"],
      "env": {
        "REGISTRY_URL": "https://your-registry.example.com",
        "NODE_ENV": "production"
      }
    }
  }
}

Shadcn Registry vs MCP Connection Failures

These are two different failure modes that look similar but require different fixes.

What Each Failure Looks Like

Testing the Shadcn Registry Directly

# Test the public shadcn registry
curl -I https://ui.shadcn.com/registry/index.json

# Test a specific component
curl https://ui.shadcn.com/registry/styles/default/button.json

# If you get 200, the registry is up and accessible

If the registry returns a non-200 response and your MCP server fetches from it, your server will fail — but the MCP connection itself may be fine. The tools will return errors, not the connection.

Registry URL Configuration

Some community shadcn MCP servers accept a custom registry URL. If you are pointing at a private or self-hosted shadcn registry, verify:

1. The URL format matches what the server expects.
2. The registry serves the correct JSON schema (shadcn registry format).
3. No authentication is required, or credentials are correctly configured.
4. The registry is network-accessible from where the MCP server process runs.

# Test your private registry
curl https://your-registry.example.com/registry/index.json

HTTP and Network Troubleshooting

If your shadcn MCP server uses HTTP or SSE transport (rather than stdio), or if it fetches data from the shadcn registry over HTTP, network issues appear differently.

Connection Refused

Symptom: ECONNREFUSED 127.0.0.1:PORT or similar.

Cause: The server is not running on the expected port, or the port is wrong in the client config.

Fix:

# Check what is listening on the expected port
lsof -i :3000
# or
ss -tlnp | grep 3000

# Start the server manually and confirm the port it binds to
npx -y <package-name> --port 3000

Timeout Errors

Symptom: Connection hangs and then times out. May appear as MCP error 32001 (request timed out).

Common causes:

• Corporate firewall blocking outbound HTTPS to ui.shadcn.com
• VPN routing issues
• DNS resolution failure
• Slow or rate-limited registry response

Diagnose:

# DNS check
nslookup ui.shadcn.com

# Direct connectivity
curl -v --max-time 10 https://ui.shadcn.com/registry/index.json

# With proxy if applicable
curl -v --proxy http://your-proxy:port https://ui.shadcn.com/registry/index.json

If you consistently hit timeouts, see our detailed guide on fixing MCP error 32001 request timed out.

HTTP Status Codes and What They Mean

Proxy and TLS Issues

If you are behind a corporate proxy:

{
  "env": {
    "HTTPS_PROXY": "http://proxy.company.com:8080",
    "NODE_TLS_REJECT_UNAUTHORIZED": "0"
  }
}

Security note: Setting NODE_TLS_REJECT_UNAUTHORIZED=0 disables TLS verification. Only use this in development environments when you understand the risk. Never use it in production.

Authentication and Access Errors

Public Registry (No Auth Required)

The public shadcn/ui registry at ui.shadcn.com does not require authentication for read access. If you are hitting a 401 against this endpoint, the issue is likely a proxy that requires authentication, or a firewall that is intercepting the request.

Private or Self-Hosted Registry

If you or your organization runs a private shadcn registry:

1. Find the authentication method from the registry documentation (Bearer token, API key, basic auth).
2. Add the credential to the env block in your MCP config:

{
  "env": {
    "REGISTRY_TOKEN": "your-token-here"
  }
}

1. Confirm the server actually reads that environment variable — check its source code or documentation for the exact variable name.

Server Connects but Tools Are Missing

This is a separate failure mode from connection failure. The MCP handshake succeeds, the client shows the server as connected, but the tool list is empty or the tools you expect are not there.

Diagnose with MCP Inspector

MCP Inspector is the fastest way to isolate this. It lets you connect to any MCP server and manually call tools/list to see exactly what the server exposes.

# Install and run MCP Inspector
npx @modelcontextprotocol/inspector npx -y <your-package-name>

Open the Inspector UI in your browser. Go to the Tools tab and click List Tools. If tools appear here but not in your client, the problem is in the client's tool display or filtering. If no tools appear here either, the server's tool registration is broken.

For a deep dive on using this tool, see our MCP Inspector complete guide.

Why Tools Disappear

• Tool registration error: The server throws an error during tool registration but does not crash the entire process. Tools after the error point are not registered.
• Protocol version mismatch: The client expects a different MCP spec version for tool discovery.
• Conditional tool registration: Some servers only register tools when certain config or env vars are present.
• Post-init crash: The server crashes after initialize completes but before tools/list is processed.

Verify with a direct protocol call:

# Using MCP Inspector or a raw JSON-RPC call
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | npx -y <package-name>

Server Initialized but Wrong Capabilities

Some MCP clients require servers to declare capabilities in the initialize response. If the shadcn MCP server does not declare tools in its capabilities, some clients will not request the tool list.

This is a server-side bug. Report it to the package maintainer with the server's initialize response.

Connection Stopped Working After Updates

A working shadcn MCP setup that suddenly breaks after an update is almost always caused by one of these:

Package Breaking Change

# See what version you have cached
npm info <package-name> version

# Check the package's changelog or releases
# Look at https://github.com/author/package/releases

If a new version introduced a breaking change to the config format, the server may fail to start because your existing config is now invalid.

Fix:

# Pin to the last working version
npx -y <package-name>@<last-known-good-version>

In your MCP config:

{
  "args": ["-y", "<package-name>@1.2.3"]
}

Node.js or Runtime Upgrade

If you updated Node.js (e.g., from 18 to 22), some packages may break due to deprecated APIs or changed behavior.

# Confirm which node your client is using
# Add this to the server command temporarily to log the version
node -e "console.error('Node version:', process.version)" && npx -y <package-name>

shadcn Registry URL or Schema Change

If the shadcn/ui team changes the registry URL structure or JSON schema, MCP servers that hardcode the old URLs will break even though the MCP connection succeeds.

Check the shadcn/ui GitHub repository for recent changes to the registry format. Also check if the MCP server package has been updated to match.

MCP Client Update

Cursor and Claude Desktop update frequently. An MCP client update may change how server configs are parsed or how the transport handshake works.

• Check your client's release notes.
• Verify your config file format matches the current client's expected schema.
• Look for any new required fields or deprecated options.

Testing with MCP Inspector

MCP Inspector is the correct tool for confirming whether the server itself works before debugging the client. If you have not used it before, this is the process:

# Test a stdio MCP server
npx @modelcontextprotocol/inspector npx -y <your-shadcn-mcp-package>

# Test with environment variables
REGISTRY_URL=https://your-registry.example.com npx @modelcontextprotocol/inspector npx -y <package>

# Test with specific args
npx @modelcontextprotocol/inspector npx -y <package> --registry https://your-registry.example.com

The Inspector opens a browser UI at http://localhost:5173 by default.

What to check in Inspector:

1. Connection status — Does the server connect at all?
2. Server info — What name and version does it report?
3. Tools tab — Are tools listed? Are they the ones you expect?
4. Resources tab — If the server exposes resources, do they load?
5. Call a tool — Try calling a specific tool and inspect the response.

You can also use our MCP server testing tool to validate your server's behavior against the MCP specification.

Minimal Reproduction Steps

If you cannot fix the issue and need to report a bug, create a minimal reproduction before filing an issue.

# 1. Create a fresh directory
mkdir shadcn-mcp-debug && cd shadcn-mcp-debug

# 2. Try running the server in complete isolation
npx -y <package-name> 2>/tmp/shadcn-mcp-stderr.log &
MCP_PID=$!
sleep 2

# 3. Send the initialize request manually
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"debug","version":"1.0"}}}' | npx -y <package-name> 2>>/tmp/shadcn-mcp-stderr.log

# 4. Check the stderr log
cat /tmp/shadcn-mcp-stderr.log

Include the following in any bug report:

• Exact package name and version (npm info <package> version)
• Node.js version (node --version)
• npm/npx version (npm --version)
• Operating system and version
• MCP client name and version
• Exact config JSON (redact any secrets)
• Full stderr output from running the command manually
• MCP Inspector output if available

Bug Report Checklist

Before filing an issue on the package's GitHub repository:

• Confirmed the package name is correct and exists on npm
• Reproduced the failure by running the command manually in terminal
• Captured the full stderr output
• Tested with MCP Inspector to confirm whether it is a server or client issue
• Confirmed Node.js version meets the package's stated requirements
• Checked the package's open issues for duplicates
• Included the MCP client name and version
• Included exact error message (not just "failed to connect")
• Redacted any API keys or credentials from the config you share

Production and Prevention Best Practices

For teams running shadcn MCP integrations in shared environments:

Pin package versions. Using npx -y <package> without a version pin means any new publish can break your setup. Pin with <package>@x.y.z.

Use absolute binary paths. Never rely on PATH resolution in MCP client configs. Always use /usr/local/bin/node or the output of which node.

Separate registry concerns from MCP concerns. If your MCP server fetches from the shadcn registry, add health check logic that catches registry failures separately from MCP transport failures.

Log to stderr only. If you build or fork a shadcn MCP server, ensure all output goes to process.stderr, never process.stdout.

Monitor with restart policies. In production agent workflows, use a process supervisor that can restart the MCP server if it crashes. See our MCP in production guide for deployment patterns.

Test in CI. Add a step that runs MCP Inspector against your server and verifies the tool list matches expectations. Catch regressions before they hit developers.

# CI test example
npx @modelcontextprotocol/inspector --cli npx -y <package> --method tools/list

Document environment variables explicitly. Every required env var should be in your team's setup documentation with the exact variable name, expected format, and where to get the value.

Common Error Messages Decoded

Related Resources

If your failure mode is a general MCP connection issue not specific to shadcn, our broader MCP server failed to connect causes and fixes covers the full spectrum of connection failures across all MCP servers.

For JSON-RPC transport-level debugging and understanding what the raw MCP protocol looks like, the MCP failed to connect guide provides lower-level protocol diagnostics.

To validate any MCP server — shadcn-related or otherwise — against the spec without setting up a full client, use MCPForge's MCP server testing tool.