How to Connect an MCP Server to Claude Code and Cursor

Connecting an MCP server is mechanical, but it contains a few places where half an hour disappears. Here is the order and how to verify each part.

Where the configuration lives

Clients typically offer two levels, and the choice matters more than it looks.

User level. A file in your profile. The server is available across all your projects. This is where general-purpose tools and anything tied to your personal credentials belong.

Project level. A file in the repository. Everyone who opens the project gets the server. This is where team-wide things belong: the project database, its tracker, its environment.

A consequence of the project level: cloning somebody else’s repository also gives you their server configuration. Convenient, and it means an unfamiliar project can bring along a server you have not inspected. Treat it like a dependency - see security.

Connecting, step by step

1. Work out the server type. A local one is launched by the client as a process, and the config carries a launch command. A remote one is an address.

2. Add the entry to the configuration. At minimum a server name plus a command or address. The name is arbitrary, but it ends up in tool names, so short and clear is better.

3. Move secrets into environment variables. Tokens and passwords must not sit in the file, especially a project-scoped one. The config references a variable; the value lives in the environment.

4. Test the launch command on its own. Run it in a terminal and confirm it starts. Half the problems surface here in under a minute.

5. Restart the client. Configuration is read at startup.

6. Verify the server is visible - see below.

On Cursor specifically: the mechanics are the same but the file location and interface differ - details in MCP servers in Cursor. On Claude Code specifics, see MCP servers in Claude Code.

Verifying the server is visible

Three levels of check, and all three are worth doing.

Status in the server list. Shows whether the process started. A server marked failed has a launch problem: command not found, dependency missing, port taken.

The tool list. Ask the agent which tools it has. A server can be listed as running and expose nothing, which usually means authentication failed. An empty tool list on a live server is almost always a wrong or missing token.

A real call. Ask for something small and safe through it. Only this confirms the whole chain: the client found the server, the server exposed tools, a tool ran, a result came back.

When the server does not appear

In descending order of frequency:

• You did not restart the client. Check this first.
• Command not found. The client launches the process in its own environment, where PATH may differ from your shell. Use the full path to the executable.
• A typo in the config. Broken JSON is often ignored silently: the client reads the file, cannot parse it, and behaves as though no servers exist. Validate the syntax.
• An empty environment variable. To the server an empty variable looks exactly like a missing one, and it fails during initialisation.
• The server needs installing. Some launch through a package manager and download on first run; without network access, or behind a proxy, the launch fails.
• The wrong configuration level. You added it to the project file and opened a different project.

If the server starts by hand but not from the client, it is almost always the environment: paths, variables or permissions. Configuration and debugging are covered in setup.

After connecting

Two habits that save time later:

Do not connect what you do not use. Every server occupies context with tool descriptions in every task. Three servers you need beat ten kept just in case.

Check the permissions. A server with write access does what it is told. Start with reads and add writes deliberately - see security and permissions.

The overview is in the MCP guide.