Flori / Blog

Cursor MCP: how to add an MCP server to Cursor

By the Flori team · Published 2026-10-27 · Updated 2026-10-29

To add an MCP server to Cursor, either install it from the Cursor Marketplace with "Add to Cursor," or add an entry to an mcp.json file: .cursor/mcp.json in your project for one project, or ~/.cursor/mcp.json for every project. Remote servers need only a URL and a browser sign-in. Local servers need a command Cursor can run.

As of October 2026. Cursor details come from Cursor's MCP documentation and can change between releases. If a menu looks different, the docs page is the source of truth.

What can Cursor do through an MCP server?

An MCP server lets Cursor's agent read tickets, look up errors, query databases or update tasks through connected tools.

MCP (Model Context Protocol) is the open standard Cursor uses to connect its agent to other tools. Once a server is connected, the agent can call that server's tools in chat: read a ticket, look up an error, query a database or update a task. If MCP itself is new to you, start with What is MCP? and come back.

Where does Cursor keep MCP settings?

Cursor reads MCP servers from two files, per its docs:

Both files use the same shape: a top-level "mcpServers" object, with one named entry per server. You manage servers you have added, including turning them on and off, from Customize in Cursor's sidebar. Disabled servers do not load and do not appear in chat.

A practical rule: put personal tools (your own project board, your notes) in the global file, and put tools the whole team needs for one codebase in the project file. Never commit secrets in a project file; use the environment variable syntax described below.

Remote servers vs stdio servers

Cursor supports three transports. In practice you choose between two kinds of server.

A remote entry is small. For example, a server named flori would be written as {"mcpServers": {"flori": {"url": "https://useflori.com/mcp"}}}. When Cursor connects, it opens a browser sign-in if the server asks for one.

A stdio entry tells Cursor what to run. The docs example uses "command" set to npx and "args" set to the package name, with keys in "env". Cursor's field table marks "type" as "stdio" for these entries, so include it. You can also point "envFile" at a .env file, but only for stdio servers.

How do I add a remote MCP server to Cursor?

To add a remote MCP server to Cursor, check the Marketplace first or add the server's URL in Cursor's MCP settings.

1. Check the Marketplace first. If the tool is listed, choose "Add to Cursor," which installs and authenticates it for you.
2. Otherwise, open the right mcp.json. Create .cursor/mcp.json in your project, or ~/.cursor/mcp.json for global use, if it does not exist.
3. Add an entry with the server URL. Give it a short name, such as "flori" or "docs," and set "url" to the address the vendor publishes.
4. Save and check Customize. The server should appear in the list. Make sure its toggle is on.
5. Sign in when asked. Cursor supports OAuth for remote servers using the authorization code flow with PKCE, and registers itself automatically when the server allows it.
6. Test with a read-only question. Ask the agent something that needs the server, like "List my open tasks," and check the answer against the app.

How do I add a local stdio MCP server to Cursor?

To add a local stdio MCP server to Cursor, install the server's runtime and configure the command that starts the server.

1. Install whatever the server needs to run, such as Node.js for npx-based servers.
2. Add an entry with "type": "stdio", "command", "args" and any "env" keys.
3. Keep secrets out of the file. Cursor resolves ${env:NAME} inside "command", "args", "env", "url" and "headers", so you can reference an environment variable instead of pasting a key. ${workspaceFolder} and ${userHome} also work.
4. Save, confirm the server is on in Customize, and test.

Only run local servers you trust. The official MCP security guidance notes that local servers run with your own account's access, so a bad one can do anything you can.

How do tool approvals work for Cursor MCP servers?

By default, Cursor asks for approval before the agent uses an MCP tool. You can expand a tool call to see its arguments before you approve it, which is the easiest way to catch an update you did not intend. MCP tools follow the same Run Modes as terminal commands, so if you loosen approvals for the terminal, think about whether you want the same for tools that change data.

For tools that write to a shared record, a good default is: approve reads freely, read the arguments on every write.

Cursor MCP not working? Troubleshooting checklist

Cursor's docs point to one place first: open the Output panel (Cmd+Shift+U on Mac), then choose "MCP Logs" from the dropdown. The logs show startup, tool calls, authentication problems and crashes. Then work through this list:

1. Server missing from Customize. The JSON is probably invalid. Check for a missing comma or quote, and make sure entries sit inside "mcpServers."
2. Server listed but off. Turn its toggle on. Disabled servers do not load.
3. Sign-in window never appears. Remove the server, save, add it again and reconnect. If the vendor gives a manual setup, use it.
4. Signed in but tools fail. Check what access you granted. Many servers separate read-only from update access, and a read-only grant will reject writes.
5. stdio server crashes on start. The command is usually not on your PATH, or a required "env" value is empty. Run the same command in a terminal to see the real error.
6. Wrong project's tools. A project file and the global file can both define servers. Check both.
7. One server fails, others work. That is expected. Cursor marks the failed call and keeps the other servers running, so fix the one server rather than restarting everything.

Worked example: connecting Flori to Cursor

Flori is a CRM with project management that small teams run with their own assistants. It publishes a remote MCP server at https://useflori.com/mcp with OAuth sign-in, so the setup is the remote path above.

1. Go to the Cursor connect page and choose Open Cursor on the computer where Cursor is installed.
2. Review the Flori connection Cursor offers and accept it.
3. Sign in to Flori in the browser. Choose the workspace or a single project, and read-only or update access.
4. Turn the connection on for your agent in Customize.
5. Ask: "Read my Flori task for the login fix, then tell me the next step."

If the Open Cursor button does nothing, use the manual setup shown in the connection flow, which is the same remote URL entry described above. You can check progress on the Cursor integration page.

Once connected, Cursor can read the project brief before it starts, reserve a task marked Ready for AI so other connected assistants can see the claim and wait, and save the outcome, proof link and next step to the task. A submitted work result has a review path; a direct task update can save immediately. Check the actual saved record and attribution. Flori sells no AI credits; Cursor runs on your own Cursor plan. The MCP project management guide covers the other assistants.

FAQ

Where is the Cursor MCP config file? Cursor reads two files. .cursor/mcp.json in a project root applies to that project only. ~/.cursor/mcp.json in your home folder applies to every project. Both use an "mcpServers" object with one named entry per server. Servers installed from the Cursor Marketplace are managed from Customize in the sidebar.

Does Cursor support remote MCP servers with OAuth? Yes. Cursor's docs say remote servers over Streamable HTTP or SSE support OAuth using the authorization code flow with PKCE. Cursor can register itself as a client automatically, or you can supply a client ID in an "auth" object if the server requires static credentials.

What is the difference between stdio and a URL in Cursor's mcp.json? A "url" entry points to a remote server that runs elsewhere and usually signs in through the browser. A stdio entry gives Cursor a "command" and "args" to start a program on your computer, with any keys in "env." Remote servers are simpler to set up; stdio servers can reach local files and programs.

How do I see why a Cursor MCP server failed? Open the Output panel with Cmd+Shift+U, then choose "MCP Logs" from the dropdown. The logs show initialization, tool calls, authentication issues and crashes. If one server fails, Cursor marks that tool call as failed in chat and keeps the other servers working.

Can I stop Cursor from changing data through MCP? Yes, in two ways. Keep Cursor's default tool approvals, which ask before each MCP tool runs and show the arguments. And grant read-only access when the server offers it, so writes are rejected even if approved. Flori, for example, offers read-only or update access per workspace or project.