ScreenshotNeo
Sign in Get a free key

BlogAI agents

How to Run an MCP Server in Cursor

Configure local or remote MCP servers in Cursor, verify tools, fix common errors, and connect ScreenshotNeo for clean screenshots.

By the ScreenshotNeo team1 October 20266 min read

Short answer: Cursor runs MCP servers from project or global configuration. Put a server entry in .cursor/mcp.json (project) or ~/.cursor/mcp.json (all projects), choose stdio for a command Cursor launches, or configure an SSE/Streamable HTTP endpoint for a deployed server. Restart or reload Cursor, enable the server’s tools in chat, then ask Agent to call one. Cursor asks for approval by default.

This guide covers setup, remote transports, verification, security, debugging, and a working screenshot example.

1. Choose where and how Cursor should run the server

Choice Use it when
.cursor/mcp.json The tools belong to one repository or team project.
~/.cursor/mcp.json You want the server available in every project for your user account.
stdio Cursor should launch a local executable such as npx, Python, or a compiled binary.
SSE The MCP server is exposed at a deployed SSE endpoint.
Streamable HTTP The server is exposed through an HTTP endpoint that supports MCP’s streamable transport.

Cursor documents MCP configuration and transports in its MCP documentation. Its MCP directory also offers one-click installation for listed integrations.

2. Configure a local stdio server

Create .cursor/mcp.json in the project root, or edit ~/.cursor/mcp.json for a global server:

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "mcp-server"],
      "env": {
        "API_KEY": "replace-with-your-key"
      }
    }
  }
}

Replace the command, arguments, and environment variables with the server’s installation instructions. Keep secrets in environment variables rather than committing them to a repository. If the server needs a working directory, use an absolute path in its documented arguments or launcher script.

Python and other commands

{
  "mcpServers": {
    "python-tools": {
      "command": "python3",
      "args": ["/absolute/path/to/server.py"],
      "env": {
        "SERVICE_TOKEN": "replace-with-your-key"
      }
    }
  }
}

MCP servers can be written in any language that prints the stdio protocol to stdout or serves an HTTP endpoint. Do not print diagnostic text to stdout in a stdio server; send logs to stderr so protocol messages remain valid.

3. Configure an SSE or Streamable HTTP server

Use the transport and fields specified by the server’s documentation. A typical endpoint configuration has the same mcpServers map and an endpoint URL, for example:

{
  "mcpServers": {
    "remote-server": {
      "url": "https://example.com/mcp"
    }
  }
}

Some servers expose separate SSE and Streamable HTTP URLs or require OAuth. Use the exact URL and authentication flow supplied by that server; do not put bearer tokens in a committed JSON file. Cursor documents OAuth support for remote servers.

4. Start the server and verify its tools

  1. Save valid JSON and open the project in Cursor.
  2. Open Cursor Chat in Agent mode and inspect the available MCP tools list.
  3. Enable the server and the individual tools you need. Ask Agent for a named tool, or describe the task precisely.
  4. Approve the call when Cursor prompts. You can enable auto-run in settings if your workflow accepts automatic tool execution.

For a command-line check, Cursor Agent CLI detects the same MCP configuration:

cursor-agent mcp list
cursor-agent mcp list-tools <identifier>
cursor-agent mcp login <identifier>

list shows configured servers and status, list-tools shows tool names and argument schemas, and login starts authentication when a server requires it.

5. Use an MCP screenshot server in Cursor

ScreenshotNeo provides an MCP server with take_screenshot, get_page_info, and capture_pdf tools. After adding its documented MCP configuration, ask Cursor Agent for a concrete action such as “use take_screenshot for https://example.com at a 1440px viewport and save the result.” Inspect the tool schema first so your request uses the server’s actual argument names. The ScreenshotNeo docs contain the current setup and API options.

6. Security checklist

  • Review the server source and requested permissions before installing it.
  • Use a narrowly scoped API key and keep it in env or your secret manager.
  • Prefer project configuration for project-only credentials; avoid committing secrets in .cursor/mcp.json.
  • Require approval for tools that write files, call external services, or incur usage charges.
  • Audit logs and screenshots for tokens, cookies, personal data, and private URLs.

7. Troubleshooting

Server does not appear

Check that the file is exactly .cursor/mcp.json or ~/.cursor/mcp.json, the JSON parses, and the workspace is the one containing the project file. Reload Cursor, then run cursor-agent mcp list.

Command not found or server exits immediately

Cursor may have a different PATH than your shell. Use an absolute executable path or a small launcher script, confirm the runtime is installed, and run the same command manually. Check stderr for the server’s own error.

Tools list is empty

The process may be writing logs to stdout, failing MCP initialization, or using the wrong arguments. Move logs to stderr, compare your command with the vendor’s instructions, and inspect cursor-agent mcp list-tools.

Authentication fails

Verify the environment variable name and token scope. For remote servers, use cursor-agent mcp login when supported and complete the OAuth flow in the same account and workspace.

Remote server times out

Check the endpoint from the machine running Cursor, proxy and firewall rules, TLS certificates, and the server logs. Confirm you selected the transport (SSE or Streamable HTTP) that the endpoint actually implements.

Cursor asks for approval every time

This is the default safety behavior. Approve individual calls or enable auto-run in Cursor settings after reviewing the server and tool permissions.

Screenshot is blank or includes overlays

For browser-based screenshot tools, wait for the target selector or network idle, provide required cookies or headers, and hide known overlays. Bot checks and consent pages can prevent the intended document from loading.

8. Performance, reliability, and cost

  • Startup: A stdio process may pay a startup cost for each Cursor session. Keep a server process reusable when its implementation supports it.
  • Latency: Remote calls add network and authentication latency. Place the server near the services it calls and set practical timeouts.
  • Reliability: Pin package versions, use an absolute runtime path, log failures to stderr, and make tools safe to retry when possible.
  • Cost: Cursor itself does not define a universal MCP price. Any API, model, browser, or hosted server charges come from that provider; check its current terms.

Or skip the browser setup

If your goal is a clean page image or PDF rather than operating a browser in Cursor, call ScreenshotNeo directly:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, failed loads, timeouts, and cache hits are never billed, and response headers report the page verdict and billing result. ScreenshotNeo also has an MCP server for AI agents, including Cursor, plus full-page and element capture, device and viewport controls, custom CSS and JavaScript, waits, headers, cookies, blocking rules, PDFs, caching, signed links, async jobs, bulk capture, and a usage API. One thousand screenshots a month are free with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.

FAQ

Can one MCP server be shared by several projects?

Yes. Put it in ~/.cursor/mcp.json for your user account, or repeat a project entry where only selected repositories should see it.

Should I use stdio or HTTP?

Use stdio when Cursor launches a local process. Use SSE or Streamable HTTP when the server already runs as a reachable service and provides that transport.

Where do I see the tool argument names?

Inspect the server in Cursor’s tools list or run cursor-agent mcp list-tools <identifier>.

Can Cursor authenticate a remote MCP server?

Cursor documents OAuth for remote servers; use the server’s supported flow and cursor-agent mcp login where available.

Keep reading