Cursor MCP: The Complete Guide to MCP Servers

Cursor has supported the Model Context Protocol (MCP) natively since early 2025, and it remains one of the most practical ways to extend what the AI in your editor can actually do. Instead of pasting context into chat windows or writing custom prompts with file contents, MCP lets Cursor's AI agent call external tools directly — search a database, read from Notion, query your internal docs, or interact with GitHub.

This guide covers everything you need to set up and use MCP servers in Cursor: configuration, popular servers worth adding, troubleshooting, and how to connect custom data sources.

If you want to understand the protocol itself first, read What is an MCP Server?.

What Is MCP in Cursor?

MCP (Model Context Protocol) is an open standard created by Anthropic that defines how AI assistants communicate with external tools and data sources. Think of it like a USB port for AI — a standardized interface that any tool can plug into.

In Cursor, MCP support means the AI agent can:

• Call external tools — run queries, fetch data, execute actions through connected servers
• Access real-time context — pull information from databases, APIs, or documentation on the fly
• Use multiple servers simultaneously — connect to GitHub, a database, and your internal docs all at once

Cursor acts as the MCP client. You configure MCP servers (either locally or remote), and Cursor's agent discovers what tools each server offers. When the agent determines it needs external information, it calls the appropriate tool automatically.

This is fundamentally different from just adding files to context. MCP tools respond to specific queries with relevant results, powered by the server's own logic — whether that is a database query, an API call, or a semantic search over indexed content.

How to Add an MCP Server to Cursor

Adding an MCP server takes about 30 seconds. Here is the process:

Step 1: Open MCP Settings

In Cursor, open Settings (gear icon or Cmd+, on macOS). Navigate to the MCP section under Features. You will see a list of any already-configured servers and an option to add new ones.

Alternatively, you can edit the configuration file directly (covered in the next section).

Step 2: Choose Your Configuration Level

Cursor supports two levels of MCP configuration:

• Project-level: A .cursor/mcp.json file in your project root. These servers are only available when that project is open.
• Global: Configured through Cursor's settings UI or the global config file. These servers are available across all projects.

Step 3: Add the Server Configuration

For a remote SSE-based server, your .cursor/mcp.json looks like this:

{
  "mcpServers": {
    "server-name": {
      "url": "https://example.com/mcp/sse",
      "headers": {
        "Authorization": "Bearer your-token-here"
      }
    }
  }
}

For a local stdio-based server (runs as a subprocess on your machine):

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"]
    }
  }
}

Step 4: Verify the Connection

After saving the config, Cursor will attempt to connect to each server. In the MCP settings panel, you should see a green indicator next to connected servers. If a server fails to connect, you will see an error message — check the troubleshooting section below.

Once connected, the server's tools become available to Cursor's AI agent. You can ask the agent to use them directly ("search my docs for authentication flow") or the agent will call them automatically when it determines the tools are relevant.

Project-Level vs Global MCP Configuration

The distinction matters more than it seems at first.

Project-Level (.cursor/mcp.json)

Create a .cursor/mcp.json file in your project root:

{
  "mcpServers": {
    "project-docs": {
      "url": "https://mcp.vecr.io/sse/your-project-id",
      "headers": {
        "Authorization": "Bearer project-specific-token"
      }
    }
  }
}

Use project-level configuration when:

• The MCP server is specific to that project (e.g., that project's documentation or database)
• You want the config committed to version control so teammates get the same setup
• You need different server configurations per project

Important: If you commit .cursor/mcp.json to git, never include actual tokens in the file. Use environment variable references or keep tokens in a .cursor/.env file that is gitignored.

Global Configuration

Configured through Settings > MCP in Cursor. Global servers are available regardless of which project is open.

Use global configuration when:

• The server is general-purpose (e.g., GitHub, Slack, web search)
• You want the same tools in every project
• The server does not contain project-specific data

Combining Both

You can use both simultaneously. Project-level servers supplement global ones. If there is a name conflict, the project-level config takes precedence.

Popular MCP Servers for Cursor

Here are the MCP servers that are most useful for day-to-day development work in Cursor:

Filesystem

What it does: Gives the AI agent read/write access to directories on your local machine.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/projects"]
    }
  }
}

Useful when you need the agent to reference files outside your current project, like shared config or monorepo sibling packages.

GitHub

What it does: Search repositories, read issues and PRs, create branches, manage files on GitHub.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

One of the most practical servers to add. The agent can look up issues, review PR changes, and search across repositories without you leaving the editor.

Postgres

What it does: Run read-only SQL queries against a PostgreSQL database.

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://user:pass@localhost:5432/mydb"]
    }
  }
}

Helpful for debugging data issues or generating queries. The agent can inspect table schemas, run SELECT queries, and help you understand your data without switching to a database client.

Playwright

What it does: Browser automation — navigate pages, take screenshots, interact with web elements.

Particularly useful for testing workflows where you want the AI to verify UI behavior or scrape structured data from web pages.

Slack

What it does: Read and search Slack messages, post to channels, manage conversations.

Connects your team communication to your development workflow. The agent can search for relevant discussions or decisions made in Slack.

Supabase

What it does: Interact with Supabase projects — query databases, manage storage, handle auth operations.

If you are building on Supabase, this server gives the agent direct access to your backend without manual API calls.

Notion

What it does: Search and read Notion pages, databases, and blocks.

Good for teams that keep specs, designs, or documentation in Notion. The agent can pull requirements or reference design docs during development.

vecr.io

What it does: Semantic search over any custom data source — GitHub repos, websites, documents, knowledge bases.

{
  "mcpServers": {
    "my-knowledge-base": {
      "url": "https://mcp.vecr.io/sse/YOUR_INTEGRATION_ID",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Unlike the other servers on this list, vecr.io is not a single-purpose connector. It generates MCP servers from any data you provide — upload documentation, point it at a repo, or crawl a website, and you get a searchable MCP endpoint. More on this below.

How to Add a Custom Data Source as MCP in Cursor

The servers listed above cover common tools, but what about your own content? Internal documentation, proprietary codebases, product specs, runbooks — the stuff that is most valuable for AI context but does not have a pre-built MCP server.

This is where vecr.io fits in. It lets you create an MCP server from any data source without writing code. Here is the walkthrough:

1. Create an Integration on vecr.io

Sign in at vecr.io and create a new integration. Give it a name like "Project Docs" or "Engineering Wiki" and pick an embedding model. BGE-M3 works well for most developer content. For content with images or diagrams, Cohere Embed 4 provides better semantic understanding.

2. Add Your Data

Upload your content directly or provide URLs:

• GitHub repos — vecr.io indexes source code, READMEs, and documentation
• Websites — Paste a URL and vecr.io crawls and indexes the site
• Files — Upload markdown, text, or PDFs directly

vecr.io chunks the content, generates vector embeddings, and builds a search index. Most datasets process in seconds.

3. Generate a Token

In the MCP tab of your integration, create an access token. Give it a name, set an expiration, and copy the token.

4. Add to Cursor

Create or edit your .cursor/mcp.json:

{
  "mcpServers": {
    "my-knowledge-base": {
      "url": "https://mcp.vecr.io/sse/YOUR_INTEGRATION_ID",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Replace YOUR_INTEGRATION_ID with the integration UUID from your dashboard and YOUR_TOKEN with the token from Step 3.

5. Use It

Once connected, Cursor's agent can search your indexed content. Ask it things like:

• "Search the knowledge base for how we handle authentication"
• "Find relevant documentation about our deployment pipeline"
• "What does our API reference say about rate limiting?"

The agent calls the MCP search tool, retrieves semantically relevant results from your data, and uses them as context for its response. This is fundamentally different from dumping files into context — the agent gets precisely the relevant chunks based on semantic search, not just whatever files happen to be open.

Troubleshooting Common MCP Issues in Cursor

Server Shows "Disconnected" or Red Indicator

• Check the URL or command. Typos in the endpoint URL or command path are the most common cause. For SSE servers, verify the URL is reachable from your machine (curl the endpoint).
• Verify authentication. If the server requires a token, make sure the headers or env block has the correct credentials. Expired tokens are a frequent culprit.
• Check your network. If you are behind a corporate VPN or firewall, SSE connections may be blocked. Try accessing the endpoint URL directly in a browser.

Server Connected but Tools Not Appearing

• Restart Cursor. After changing MCP config, a full restart sometimes helps where a reconnect does not.
• Check the server logs. For stdio-based servers, errors during startup may prevent tool registration. Run the command manually in a terminal to see error output.
• Validate JSON syntax. A trailing comma or missing bracket in mcp.json will silently fail. Run the file through a JSON validator.

Agent Not Using MCP Tools

• Be explicit. Sometimes the agent needs a nudge. Instead of "help me with authentication," try "use the docs MCP to search for authentication."
• Check tool availability. In Cursor's MCP settings, verify the server shows its tools listed. If no tools appear, the server may have connected but failed to register them.
• Reduce ambiguity. If you have many MCP servers connected, the agent may not know which one to use. Name your servers descriptively so the agent can match intent to the right tool.

Authentication Errors (401/403)

• Regenerate the token. Tokens may have expired or been revoked. Create a new one and update the config.
• Check token format. Make sure the Authorization header includes the Bearer prefix: "Bearer your-token", not just "your-token".
• Verify scopes. Some servers require tokens with specific scopes or permissions. Check the server's documentation for required access levels.

Best Practices for Using MCP in Cursor

Keep the number of servers reasonable. Each connected server adds tools to the agent's context. Too many servers (10+) can dilute the agent's ability to pick the right tool. Connect what you actively use.

Use project-level configs for project-specific servers. A database server for Project A should not be globally available when you are working on Project B. It adds noise and potential security risk.

Rotate tokens regularly. Especially for tokens committed to shared repos (even as environment variable references). Treat MCP tokens like any other API credential.

Name servers descriptively. The server name in your config helps the agent understand what each server does. "engineering-docs" is better than "server-1". "project-db" is better than "postgres".

Test in the playground first. Before relying on an MCP server in your workflow, test it independently. vecr.io includes a built-in playground; many other servers have similar testing tools. Verify the server returns useful results before integrating it into your daily work.

Commit project configs, not secrets. Add .cursor/mcp.json to version control so your team shares the same MCP setup. Keep tokens in environment variables or a gitignored file.

Getting Started

If you are already using Cursor, adding MCP servers is one of the highest-leverage things you can do to improve your workflow. Start with the GitHub server and one or two others relevant to your stack.

For custom data — internal docs, proprietary codebases, knowledge bases — vecr.io generates a searchable MCP server in minutes with no code required. The free tier includes 500 API calls per month and up to 10 pages of indexed content: enough to test the full workflow and see how semantic search from inside Cursor changes how you work.

Create your first MCP server on vecr.io