MCP in Claude Code and Cursor: what it is and how to set it up

The short answer

MCP (Model Context Protocol) is an open standard that connects an AI agent to external tools and data, useful for anyone who already writes code with Claude Code or Cursor and wants the agent to query real systems instead of receiving text pasted into the chat. The official documentation describes it as "an open-source standard for connecting AI applications to external systems" and uses the USB-C port analogy: one connector, many devices. In practice, the whole configuration fits in two JSON files: .cursor/mcp.json in Cursor and .mcp.json in Claude Code. The agent reads that file, starts the server and begins to see the tools it exposes. Almost every first-time problem lands on the same spot: the local server does not start because the command is not on the editor's PATH or because the Node version is too old. Below are both configurations, with the Shopify Dev MCP as the example, and the line between a file error and an environment error.

1. What MCP is, in three layers

The protocol's architecture documentation splits the subject into parts worth remembering, because every error shows up in one of them.

Participants. There is the host (the AI application, such as Claude Code or Cursor), the client (one dedicated connection per server) and the server (the program that delivers context and tools). The host opens one client per configured server, which is why one broken server does not take the others down.

Data layer. A protocol based on JSON-RPC 2.0. This is where the server primitives live: tools (executable functions), resources (data sources) and prompts (interaction templates). The client discovers what exists with listing calls and executes with tools/call.

Transport layer. Defines the path the messages travel. There are two transports: stdio, which uses standard input and output between processes on the same machine, and Streamable HTTP, which uses POST with optional Server-Sent Events and accepts a bearer token, an API key or headers. The official recommendation for obtaining a token is OAuth.

The protocol is versioned by date. The current version is 2026-07-28, and the number only changes when there is a breaking change. Negotiation happens per request, and the server rejects a version it does not support.

2. The two transports and when to use each

The transport decides where the code runs, who pays for the infrastructure and how you authenticate. Cursor documents the comparison like this:

Source: Cursor Docs, Model Context Protocol (MCP) page, read on 21/09/2026.

Rule of thumb: stdio for a tool that touches your disk, your local database or a script of yours. HTTP for a third-party cloud service and for teams, because one server serves many clients and authentication follows OAuth instead of environment variables scattered across machines.

Claude Code documents HTTP as the recommended option for remote servers and marks SSE as a deprecated transport. Servers that only expose SSE keep working: recent versions try HTTP first and fall back to SSE when the server does not accept it.

3. Where the configuration really lives

An install button in a marketplace is a convenience. What rules is the file, and knowing which file the agent read solves half the problems.

Cursor

Two places, and the difference is reach:

• .cursor/mcp.json at the project root: applies only to that project.
• ~/.cursor/mcp.json in your home directory: applies to every project.

A stdio server in Cursor uses the fields type, command, args, env and envFile. The documentation is explicit about command: it "must be available on your system path or contain its full path". Keep that sentence in mind, because it is the cause of the error in section 5. envFile only exists for stdio.

Claude Code

Three scopes, and each one writes to a different place:

Source: Claude Code documentation, MCP page, read on 21/09/2026.

The file you commit is .mcp.json. It uses the same mcpServers key as Cursor, which lets you copy a block from one to the other in most cases. For safety, Claude Code asks for interactive approval before using servers that come from .mcp.json: a cloned repository does not switch on a server by itself.

When the same name appears in more than one scope, Claude Code connects only once, using the definition with the highest precedence, without mixing fields. The order is local, project, user, plugin servers and connectors.

4. Setting it up in practice: the same server in both editors

The example uses the Shopify Dev MCP, the official server that gives the agent access to the developer documentation, the API schemas and validation for GraphQL, Liquid and extensions. It works as an example because it runs locally, over stdio, and does not require authentication.

Requirement before any file

The Shopify AI Toolkit requires Node.js 18 or later. Check the version in the same shell that opens the editor:

node -v
npx -y @shopify/dev-mcp@latest --help

If the second command does not respond, the problem is the environment, not the JSON. Fix it here before editing any configuration.

Claude Code

The documented way uses the CLI, which writes the configuration for you:

claude mcp add --transport stdio shopify-dev-mcp \
  -- npx -y @shopify/dev-mcp@latest

The -- separates Claude Code's options from the command that starts the server. Without it, the CLI reads the server's flags, such as -y, as if they were its own. To share it with the team, add --scope project, which writes to .mcp.json.

The resulting file, if you prefer to write it by hand at the project root:

{
  "mcpServers": {
    "shopify-dev-mcp": { "command": "npx", "args": ["-y", "@shopify/dev-mcp@latest"] }
  }
}

After that, restart Claude Code to load the new configuration. Inside the session, /mcp shows the panel with the status and the tool count for each server.

Cursor

Same block, in .cursor/mcp.json at the project root:

{
  "mcpServers": {
    "shopify-dev-mcp": { "command": "npx", "args": ["-y", "@shopify/dev-mcp@latest"] }
  }
}

Save and restart Cursor. On Windows, the Shopify documentation records an alternative for when a connection error shows up: change command to cmd and pass ["/k", "npx", "-y", "@shopify/dev-mcp@latest"] in args.

Verification

In Claude Code, claude mcp list shows the status of each server: connected, needs authentication or failed to connect. In Cursor, the server shows up in the chat's tools panel, and the log is in Output, MCP Logs option.

5. The classic error: the stdio server that does not start

A remote server fails with an HTTP status, which is readable. A stdio server fails silently, and almost always for one of these reasons.

A PATH different from the one you see in the terminal

A stdio server is a process the editor launches, and it inherits the editor's environment, not your terminal's. If you installed Node through nvm, asdf, Volta or Homebrew and opened the editor from the desktop icon, the npx that works in the terminal may not exist for the editor. That is what the Cursor documentation guards against when it requires command to be on the system PATH or given as a full path.

Two ways out. The direct one is to find the absolute path and use it:

which node
which npx

And then replace "command": "npx" with that absolute path in the JSON. The other is to open the editor from the already configured terminal, so the process inherits the right PATH.

Node version below the requirement

The Shopify toolkit requires Node.js 18 or later. With nvm, the version active in the terminal is not necessarily the one the editor sees. The symptom is a server that shows up as failed with no clear message, or that dies right after starting. Run node -v through the absolute path you put in the JSON, not through your shell's.

Entry with url and no type

A file error, not an environment error. Claude Code reads an entry without type as a stdio server. So an entry with url and no type is an invalid configuration: the server is skipped and the message is MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry. In versions before 2.1.202, the same configuration showed up as command: expected string, received undefined, which sends the developer looking in the wrong place. When you copy an mcpServers block written for another client, check that the entries with url declare type.

Invisible whitespace in a pasted token

Claude Code warns when a configuration value carries whitespace at the beginning or the end, typical of a token pasted with a line break. The check covers command, url, each item in args and the values and key names in env and headers. The warning names the field without printing the value, and the agent does not trim the space on its own. Fix it in the file.

Short startup time

A server that downloads a package on the first npx takes longer than usual. In Claude Code, the startup time can be configured through an environment variable:

MCP_TIMEOUT=10000 claude

The value is in milliseconds, so this example gives the server ten seconds to start.

Reconnection that does not exist

Remote servers that drop in the middle of a session are reconnected by Claude Code with exponential backoff, up to five attempts. stdio servers are not: they are local processes and have no automatic reconnection. If the process died, reconnect through the /mcp panel or restart the session.

6. Secrets, scope and what not to commit

.mcp.json at the root is meant to go into the repository, and that is where the risk shows up: an API key written straight into the JSON goes along with the commit.

Both editors solve this with interpolation. Cursor resolves variables in command, args, env, url and headers, with the syntaxes ${env:NOME}, ${userHome} and ${workspaceFolder} (the folder that contains .cursor/mcp.json). Claude Code expands ${VAR} and accepts a default value in the form ${VAR:-default}.

The shared block references the variable, and each person on the team sets the value on their own machine:

{ "mcpServers": {
  "api-interna": {
    "type": "http", "url": "https://api.exemplo.com/mcp",
    "headers": { "Authorization": "Bearer ${env:API_TOKEN}" }
  }
} }

Three precautions that are worth more than any configuration trick:

1. Keys with minimum permissions. If the agent only needs to read orders, the key does not need to create customers.
2. A third-party server is code running on your machine, with your access. The Claude Code documentation is direct in asking you to check that you trust the server before connecting, because servers that fetch external content expose you to prompt injection risk. Cursor recommends reviewing the source code for critical integrations.
3. A sensitive environment calls for local stdio instead of a remote endpoint, in line with Cursor's own recommendation on sensitive data.

7. Limits that show up once the server works

A connected server does not mean a solved workflow. Two documented limits show up quickly in real use.

Output volume. Claude Code warns when the output of an MCP tool exceeds 10,000 tokens and caps the output at 25,000 tokens by default. You can raise the ceiling with MAX_MCP_OUTPUT_TOKENS; the warning threshold is fixed. A tool that returns a whole table dump hits that ceiling, and the way out is usually filtering on the server, not raising the limit.

Idle time per call. A call that neither responds nor sends a progress notification within the idle window aborts with an error instead of waiting for the wall-clock limit. The default window is five minutes for HTTP, SSE, WebSocket and connectors, and 30 minutes for stdio. Long jobs require a server that emits progress.

Source: Claude Code documentation, MCP page, read on 21/09/2026.

If your use case is running an agent on a machine that stays on all the time, the environment and PATH logic in this section applies the same way, and keeping Claude Code on a server is covered in Claude Code 24/7 on a Hostinger VPS.

Frequently asked questions

Does MCP replace the API of the system I want to integrate?

No. MCP is the connection layer between agent and tool; the API is still the API. The MCP server talks to your system and exposes it as tools, resources or prompts. If the system has no API and no accessible database, MCP does not create access that does not exist.

Can I use the same configuration in Cursor and Claude Code?

In most cases, yes: both read the mcpServers key in the same format. The Claude Code documentation points out the two common fixes when reusing a block written for another client: add type to entries with url and rename servers whose names have characters other than letters, numbers, hyphens and underscores.

Why does the server work in the terminal and fail inside the editor?

Because the server process inherits the editor's environment, not your terminal's. Node version managers change the PATH per shell, and an editor opened from an icon does not go through that shell. Use the absolute path in the command field or open the editor from the already configured terminal.

Is a third-party MCP server safe?

It depends on who published it and what it accesses. The Claude Code documentation asks you to check that you trust the server before connecting, because servers that bring in external content create prompt injection risk. Cursor recommends installing from a trusted source, reviewing what the server accesses, using a key with restricted permissions and reading the code for critical integrations.

Do I need MCP for the agent to understand my Shopify project?

Not necessarily. Shopify offers the toolkit as a plugin, as agent skills and as the Dev MCP, and treats the plugin as the recommended path, with automatic updates. MCP is the path when the agent needs to talk to a system only you have, such as an ERP, an internal database or your own dashboard.

Conclusion

MCP solves a specific problem: giving the agent a standardized path to the tool, instead of you pasting data into the chat. The configuration is small and lives in two files, .cursor/mcp.json and .mcp.json, with the same mcpServers key. What breaks is almost never the JSON itself: it is the command that is not on the editor's PATH, the Node version below the requirement or the entry with url and no type. Start with a single server, check its status before asking the agent for anything and only then add the second one.

If what you need is the agent reading your ERP, your store or your database, that is a custom integration (MCP, webhook, queue). Describe the system and what you want to automate at oailton.dev/en/contato.