What the MCP server does and why Cursor needs it

An MCP (Model Connector Protocol) server acts as a local or remote adapter that exposes developer-provided tools and endpoints to a client like Cursor. It normally advertises available tool endpoints, health information, and authentication requirements so the client can use tools (e.g., search, code execution, document retrieval) securely and deterministically.

When you integrate Cursor with an MCP server such as the @21st-dev/magic MCP server, Cursor queries the MCP for the list of tools, their signatures and endpoints. If the MCP fails to list tools, Cursor reports the dreaded “No tools available” message — a symptom, not a cause. The root cause can be configuration, network, or authentication related.

This guide focuses on concrete installation steps, configuration patterns and troubleshooting flows: installing the @21st-dev/magic MCP server, how to pass API keys, common connection issues, and checks to reduce downtime. Expect examples for local development (localhost) and production (TLS, reverse proxies).

Installing the @21st-dev/magic MCP server

Install the package into a Node environment used as your MCP host. For most projects, a standard npm or yarn install is all you need. Example (from your project root):

npm install @21st-dev/magic --save
# or
yarn add @21st-dev/magic

Once installed, create a minimal server bootstrap. The @21st-dev/magic package exposes an HTTP/Express-friendly entry that advertises the tool registry and health endpoints Cursor expects. Run it under PM2, systemd, or a container for reliability. Keep logs accessible for quick diagnosis.

Deploy patterns differ: for local testing, bind to 127.0.0.1:PORT and use a simple environment file. For production, front the MCP with a reverse proxy (Nginx) and TLS termination. Always confirm the advertised base URL matches the externally reachable host so Cursor can fetch the tool manifests without CORS or host mismatch errors.

Passing API keys and secure MCP configuration

Cursor and your MCP server often need API keys or tokens to authenticate requests to third-party tools (and optionally to authenticate Cursor itself). Best practice: do not bake secrets into source code. Instead, inject via environment variables, secret managers, or mounted files in containers. Example environment variables:

MCP_PORT=8080
MCP_BASE_URL=https://mcp.example.com
OPENAI_API_KEY=sk-...
TOOL_X_TOKEN=token-for-tool-x

In your server code, validate that environment keys exist at startup with a clear error and exit if required values are missing. This avoids runtime “No tools available” scenarios caused by conditional tool registration failing silently because a key was absent.

If Cursor must call the MCP with client-side tokens, prefer short-lived tokens signed by a secure backend. If Cursor runs in a hosted environment, consult its docs for token exchange flows and make sure MCP supports those headers or query parameters. Always document the expected header names (Authorization: Bearer or X-API-Key: ) so integration is deterministic.

Common connection issues and the “No tools available” error

When Cursor reports “No tools available”, treat it as a widget: first verify the MCP is healthy and responding with the tool manifest. The manifest is typically a JSON object listing available tools, endpoints and capabilities. A missing or empty manifest can be caused by startup failures, environment keys absent, or an authorization check that prevents listing tools.

Network issues are surprisingly frequent: firewalls, SELinux policies, loopback binding, or reverse-proxy misconfiguration can block Cursor. If Cursor and MCP run on different hosts, verify port, TLS, and possibly the need for CORS headers if Cursor fetches manifests client-side. For server-to-server connections, CORS isn’t an issue but firewalls and routing are.

Authentication failures manifest as 401/403 responses when Cursor attempts to fetch the tool registry. Check logs on both sides. Instrument your MCP to log the incoming request path, authorization header presence, and the internal reason a tool was/wasn’t registered. These logs are your best friend when fixing “No tools available”.

Troubleshooting checklist and quick fixes

Start with these deterministic checks in order — they eliminate the most common causes quickly and with minimal guesswork:

• Confirm MCP process is running and listening on the configured port (ss/netstat).
• Fetch the tool manifest directly: curl -v http(s)://MCP_BASE_URL/.well-known/mcp-tools or the package-specific endpoint
• Inspect server logs for startup errors related to missing env vars or failed tool registration.
• Check network/firewall rules and reverse proxy headers (X-Forwarded-Proto, Host).
• Verify Cursor’s configured endpoint exactly matches the MCP’s publicly reachable base URL (including scheme and port).

A sample curl test that will reveal many problems quickly:

curl -i -H "Authorization: Bearer <token>" https://mcp.example.com/.well-known/mcp-tools
# Expect 200 and JSON listing tools; 401/403 indicates auth issues.

If the manifest is empty, add diagnostic logging when you register tools to show whether registration code executed and which conditional branches prevented registration (missing API keys, disabled features, feature flags off, etc.).

Example MCP server bootstrap and configuration notes

Here is a concise Node-style bootstrap example (adapt to your framework):

const { createMcpServer } = require('@21st-dev/magic');
const server = createMcpServer({
  port: process.env.MCP_PORT || 8080,
  baseUrl: process.env.MCP_BASE_URL,
  tools: [
    // register tools only when required env keys exist
    process.env.TOOL_X_TOKEN ? { name: 'tool-x', url: '/tool-x' } : null
  ].filter(Boolean),
});
server.listen();

Note the conditional registration pattern: tools that depend on API keys are only registered when keys are present. If keys are missing, the tool is omitted and Cursor sees fewer tools. Choose whether to fail-fast (preferred) or to register a placeholder that returns an informative error to the caller.

For production, run the MCP process under a supervisor (systemd/PM2/docker). Configure health and readiness probes so external orchestrators know when the tool manifest is stable and Cursor can attempt to use it. Use structured JSON logs to make parsing and alerting easier.

When to enable advanced diagnostics

Switch on verbose logging during integration tests or if you encounter intermittent “No tools available” or flapping connections. Capture request/response traces and the sequence of registration events. Keep verbose logs off in production unless troubleshooting, and route them to a secured log store.

If you suspect TLS/hostname mismatches, run openssl s_client -connect host:port and check certificates. If your MCP is behind a proxy that rewrites Host or X-Forwarded-Proto, make sure it preserves the original values required by Cursor or that your MCP validates accordingly.

Finally, consider adding a simple health endpoint that emits the number of registered tools, uptime and last registration error. Cursor administrators will appreciate a single, predictable endpoint to verify integrations programmatically.

Backlinks & further reading

Primary package and docs for the MCP server in this guide: @21st-dev/magic MCP server docs.

If you want to re-run the installation steps or revisit configuration examples, see the @21st-dev/magic MCP server documentation: @21st-dev/magic MCP server.

Troubleshooting “No tools available” and connection guidance: Cursor MCP troubleshooting & configuration.

Semantic core (expanded keyword clusters)

Primary keywords

• Cursor MCP Servers
• @21st-dev/magic MCP server
• Cursor “No tools available” error
• MCP server connection issues
• Cursor MCP configuration

Secondary keywords / intent-based queries

• passing API key to MCP server
• @21st-dev/magic installation
• troubleshooting MCP server errors
• MCP tool manifest missing
• Cursor tool registry fetch

Clarifying LSI phrases and related formulations

• MCP config, tool registration, API token env var
• manifest endpoint, .well-known/mcp-tools, health probe
• reverse proxy, TLS termination, CORS, 401/403 auth failures
• diagnostic logs, startup validation, fail-fast

FAQ

Q: Why does Cursor show “No tools available” after I install @21st-dev/magic?

A: That message means the MCP manifest is empty or inaccessible. Verify the MCP process is running, fetch the manifest directly (curl your MCP /.well-known or package-specific endpoint), and check logs for missing API keys or conditional code that skipped tool registration. Also confirm Cursor is configured to hit the correct base URL (scheme, host, port).

Q: How do I pass API keys to the MCP server securely?

A: Use environment variables, a secrets manager, or mounted secret files; avoid hard-coding keys. At startup, validate required env vars and fail-fast with a clear error if missing. For Cursor-hosted environments, use short-lived tokens or an authorization exchange rather than embedding long-lived secrets in the client.

Q: Cursor can’t connect to my MCP server — what network checks should I run?

A: Confirm the server listens on the expected port (ss/netstat), test the endpoint with curl including any Authorization header, inspect firewall and reverse-proxy rules, and ensure TLS certificates and hostnames match. If you see 401/403 responses, inspect authorization headers and token formats on both sides.