Cursor MCP Server Guide: Configure, Integrate @21st-dev/magic, and Fix «No tools available»

This article explains how to configure Cursor MCP servers, integrate the @21st-dev/magic tool adapter, set environment variable API keys, and troubleshoot common MCP protocol issues — including the dreaded «No tools available» error. It focuses on practical steps you can run now, with the minimal theory needed to understand why each step matters.

If you want the short answer first: ensure your MCP server is running the correct protocol version, the tool registry is reachable and registered, and the environment variable/API key your Cursor or client process uses is present and valid. If any of those fail, Cursor reports «No tools available» even if the server is up.

Quick troubleshooting summary

• Check environment vars and API key presence on the MCP server and client.
• Confirm protocol compatibility and version match (handshake logs).
• Verify the tool registry registration and tooling manifest the server exposes.

What is Cursor MCP and how MCP servers work

Cursor MCP servers implement the MCP (Magic Connector Protocol) endpoint that clients — like the Cursor runtime or other magic tool integrations — call to discover and use «tools» (models, actions, or handlers). The MCP server advertises available tools and negotiates secure connections and requests with clients.

MCP servers typically expose a REST or WebSocket API and expect authenticated clients. A successful MCP handshake includes client authentication (often via an API key or bearer token), tool discovery, and tool-specific capability exchange. If any negotiation step is missing, the client may show «No tools available» even though the network path works.

In production, MCP servers should be behind TLS and optionally behind a reverse proxy. Tool discovery and registration can be dynamic (server ad-hoc registers tools on startup) or static (configured via manifest files). Pay attention to how your MCP server populates its tool registry; that’s where most «missing tool» issues begin.

Environment variable API key setup (best practices)

The most common authentication mechanism for MCP servers is an API key set in environment variables on both server and client processes. Use clear names and consistent defaults: for example, MCP_API_KEY or CURSOR_API_KEY. Store secret values in a secure secrets manager in production and only place them in environment variables for local testing or container runtime injection.

Example .env pattern for local development:

MCP_API_KEY="sk-prod-xxxx"
MCP_ENDPOINT="https://mcp.example.com"
CURSOR_CLIENT_ID="cursor-local"
  

On the server side, verify the env var is picked up at process start. Logging the presence (not the value) of the key is helpful: «MCP API key found: yes/no». If you use containers, provide the key via orchestration secrets (Kubernetes Secret, Docker secret) rather than baked images. Also ensure the process user has permission to read the secret file if it’s mounted.

Configuring MCP server & integrating @21st-dev/magic tool

Integration with the @21st-dev/magic tool adapter requires two configuration steps: (1) the MCP server must expose or register the tool manifest that @21st-dev/magic expects, and (2) the client (Cursor) must be configured to call the server endpoint with the correct API key and protocol. Typical configuration points are base URL, port, TLS certificate settings, and a tool manifest path or registration hook.

For practical details and implementation examples of the @21st-dev/magic integration, consult the project documentation and helper pages. A useful reference that explains common configuration patterns and troubleshooting steps is the 21st-dev magic MCP docs: 21st-dev/magic MCP docs.

When adding @21st-dev/magic, ensure the tool adapter’s manifest matches the server registry schema. Mismatched capability flags or missing endpoints in the manifest are frequent causes of clients showing zero tools. If your adapter supports dynamic registration, monitor logs for a successful «tool-registered» event.

MCP protocol compatibility and tool discovery

Protocol compatibility is not just about version numbers — it’s about the shape of the handshake, authentication schemes, and how capabilities are described. MCP implementations may add optional fields or change tool schema slightly between versions. Always test compatibility in a staging environment first.

Tool discovery often relies on a well-defined manifest (JSON/YAML) that lists tool IDs, endpoints, input/output specs, and security requirements. If the client expects a «tools» array and the server returns «instruments» (renamed field), the client will interpret that as «no tools». Validate the manifest shape with a quick schema check.

Use a packet capture, request inspector, or server-side debug logging to watch the handshake. Look for these markers: handshake start, client auth header present, server sends tool list, client confirms tools accepted. Any break in this sequence is the root cause you need to fix.

Diagnosing «No tools available» error and MCP server connection issues

«No tools available» is a symptom, not the root cause. Start by confirming the client reached the server: ping the endpoint, curl the status route, and inspect logs for incoming requests. If there are no incoming requests, the network or endpoint configuration is likely wrong (DNS, port, firewall, or proxy).

If requests arrive but the server responds with an empty tools list, check the tool registry: was the tool adapter started? Is its manifest loaded? Did registration succeed? Server logs often show a successful registration message; if not, search logs for registration errors or validation failures.

If the server and registry appear correct but the client still shows no tools, authenticate the handshake. Missing or invalid API keys result in the server returning 401/403 or an empty tool list depending on implementation. Confirm the same API key on both sides and test with a direct call using curl or a small script.

Troubleshooting checklist (run in this order)

• Verify env vars: MCP_API_KEY present on server and client.
• Confirm server reachable: curl https://mcp.example.com/status and check response.
• Check server logs for tool registration entry and handshake logs.
• Validate manifest schema and ensure it exposes expected tool names.
• Test an authenticated request (curl with Authorization header) to fetch tools.

Advanced debugging, logging, and best practices

Increase logging verbosity on both the MCP server and the @21st-dev/magic adapter during debugging. Search for handshake traces, tool registration calls, and errors. If the system uses WebSockets, ensure proxied connections maintain sticky sessions and correct headers; some load balancers terminate or change headers causing auth failures.

Add health checks that assert not only the server is alive but that it has at least one registered tool. Return a 200 with a small JSON body like { «toolsRegistered»: 3 } so orchestration can alert if the registry goes empty. This prevents silent failures where the process is up but non-functional.

In continuous delivery, avoid baking API keys into images. Use secrets injection and make configuration reloadable when possible. For dynamic environments (Kubernetes), use init containers to verify connectivity and registration prior to marking a pod ready. Finally, automate a simple handshake test as part of your deployment pipeline.

Links and further reading

Implementation notes and sample manifests are available in the maintained documentation for the adapter and helper projects. See the official reference: 21st-dev/magic MCP docs.

FAQ

Q: Why does Cursor show «No tools available» when the MCP server is up?

A: Because «up» only means the process is reachable — not that your tool registry or authentication passed. Verify the MCP server returns a non-empty tools array, confirm API keys and manifest schema, and check registration logs. Most cases are resolved by fixing environment variable placement or correcting manifest fields.

Q: How should I set the API key in production for MCP server authentication?

A: Use your platform’s secrets storage (Kubernetes Secret, cloud secret manager, or orchestration secrets) and inject the secret as an environment variable at runtime. Avoid embedding keys in images or source. On startup, log that the key is present (do not log the value), and run an automated handshake test to confirm it works.

Q: How do I confirm MCP protocol compatibility between client and server?

A: Capture the exchange during handshake (server logs, client debug output, curl/WS test). Compare the fields and version headers. Validate the tool manifest schema and ensure endpoints and capabilities match. If versions differ, consult changelogs for renamed or deprecated fields and update either client or server to align.

Primary:
- Cursor MCP servers
- MCP server configuration
- @21st-dev/magic tool integration
- MCP protocol compatibility
- "No tools available" error
- MCP server troubleshooting

Secondary:
- environment variable API key setup
- MCP server connection issues
- tool registry manifest
- tool discovery
- handshake logs
- authentication bearer token

Clarifying / LSI:
- API key environment variable
- MCP adapter
- tool manifest schema
- tool registration
- WebSocket/REST MCP endpoint
- TLS and proxy configuration
- logs and debug mode
- health checks for tools
- secrets manager injection