export const meta = {
  title: "Model Context Protocol (MCP)",
  description: "Connect Cursor to external tools and data sources using Model Context Protocol (MCP). Install servers, configure authentication, and integrate with databases, APIs, and third-party services."
};

# Model Context Protocol (MCP)

## What is MCP?

[Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) enables Cursor to connect to external tools and data sources.

<Frame>
  <video
    src="/docs-static/images/context/mcp/simple-mcp-call.mp4"
    autoPlay
    loop
    muted
    playsInline
    controls
    width={3380}
    height={2160}
  />
</Frame>

## Servers

Browse available MCP servers. Click "Add to Cursor" to install them directly.

<McpServers showMoreButton={true} maxItems={5} />

### Why use MCP?

MCP connects Cursor to external systems and data. Instead of explaining your project structure repeatedly, integrate directly with your tools.

Write MCP servers in any language that can print to `stdout` or serve an HTTP endpoint - Python, JavaScript, Go, etc.

### How it works

MCP servers expose capabilities through the protocol, connecting Cursor to external tools or data sources.

Cursor supports three transport methods:

<div className="full-width-table">
| Transport | Execution environment | Deployment | Users | Input | Auth |
|:----------------|:----------|:------------|:---------------|:----------------|:----------------|
| **<span className="whitespace-nowrap">`stdio`</span>** | Local | Cursor manages | Single user | Shell command | Manual |
| **<span className="whitespace-nowrap">`SSE`</span>** | Local/Remote | Deploy as server | Multiple users | URL to an SSE endpoint | OAuth |
| **<span className="whitespace-nowrap">`Streamable HTTP`</span>** | Local/Remote | Deploy as server | Multiple users | URL to an HTTP endpoint | OAuth |

</div>

### Protocol support

Cursor supports these MCP protocol capabilities:

<div className="full-width-table">

| Feature         | Support   | Description                                                     |
| :-------------- | :-------- | :-------------------------------------------------------------- |
| **Tools**       | Supported | Functions for the AI model to execute                           |
| **Prompts**     | Supported | Templated messages and workflows for users                      |
| **Resources**   | Supported | Structured data sources that can be read and referenced         |
| **Roots**       | Supported | Server-initiated inquiries into URI or filesystem boundaries    |
| **Elicitation** | Supported | Server-initiated requests for additional information from users |

</div>

## Installing MCP servers

### One-click installation

Install MCP servers from our collection and authenticate with OAuth.

<CardGroup cols={2}>
  <Card title="Browse MCP Tools" icon="table" horizontal href="/docs/context/mcp/directory">
    Browse available MCP servers
  </Card>

  <Card title="Add to Cursor Button" icon="plus" horizontal href="/docs/context/mcp/install-links">
    Create an "Add to Cursor" button
  </Card>
</CardGroup>

<br />

### Using `mcp.json`

Configure custom MCP servers with a JSON file:

```json title="CLI Server - Node.js"
{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "mcp-server"],
      "env": {
        "API_KEY": "value"
      }
    }
  }
}
```

```json title="CLI Server - Python"
{
  "mcpServers": {
    "server-name": {
      "command": "python",
      "args": ["mcp-server.py"],
      "env": {
        "API_KEY": "value"
      }
    }
  }
}
```

```json title="Remote Server"
// MCP server using HTTP or SSE - runs on a server
{
  "mcpServers": {
    "server-name": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "API_KEY": "value"
      }
    }
  }
}
```

### STDIO server configuration

For STDIO servers (local command-line servers), configure these fields in your `mcp.json`:

<div className="full-width-table">

| Field | Required | Description | Examples |
|:------|:---------|:------------|:---------|
| **type** | Yes | Server connection type | `"stdio"` |
| **command** | Yes | Command to start the server executable. Must be available on your system path or contain its full path. | `"npx"`, `"node"`, `"python"`, `"docker"` |
| **args** | No | Array of arguments passed to the command | `["server.py", "--port", "3000"]` |
| **env** | No | Environment variables for the server | `{"API_KEY": "${env:api-key}"}` |
| **envFile** | No | Path to an environment file to load more variables | `".env"`, `"${workspaceFolder}/.env"` |

</div>

### Using the Extension API

For programmatic MCP server registration, Cursor provides an extension API that allows dynamic configuration without modifying `mcp.json` files. This is particularly useful for enterprise environments and automated setup workflows.

<Card
  title="MCP Extension API Reference"
  icon="code"
  href="/docs/context/mcp-extension-api"
>
  Learn how to register MCP servers programmatically using
  `vscode.cursor.mcp.registerServer()`
</Card>

<br />

### Configuration locations

<CardGroup cols={2}>
  <Card title="Project Configuration" icon="folder-tree">
    Create `.cursor/mcp.json` in your project for project-specific tools.
  </Card>

  <Card title="Global Configuration" icon="globe">
    Create `~/.cursor/mcp.json` in your home directory for tools available everywhere.
  </Card>
</CardGroup>

### Config interpolation

Use variables in `mcp.json` values. Cursor resolves variables in these fields: `command`, `args`, `env`, `url`, and `headers`.

Supported syntax:

- `${env:NAME}` environment variables
- `${userHome}` path to your home folder
- `${workspaceFolder}` project root (the folder that contains `.cursor/mcp.json`)
- `${workspaceFolderBasename}` name of the project root
- `${pathSeparator}` and `${/}` OS path separator

Examples

```json
{
  "mcpServers": {
    "local-server": {
      "command": "python",
      "args": ["${workspaceFolder}/tools/mcp_server.py"],
      "env": {
        "API_KEY": "${env:API_KEY}"
      }
    }
  }
}
```

```json
{
  "mcpServers": {
    "remote-server": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MY_SERVICE_TOKEN}"
      }
    }
  }
}
```

### Authentication

MCP servers use environment variables for authentication. Pass API keys and tokens through the config.

Cursor supports OAuth for servers that require it.

## Using MCP in chat

Agent automatically uses MCP tools listed under `Available Tools` when relevant. This includes [Plan Mode](/docs/agent/planning). Ask for a specific tool by name or describe what you need. Enable or disable tools from settings.

### Toggling tools

Enable or disable MCP tools directly from the chat interface. Click a tool name in the tools list to toggle it. Disabled tools won't be loaded into context or available to Agent.

<Frame>
  <video
    src="/docs-static/images/context/mcp/tool-toggle.mp4"
    autoPlay
    loop
    muted
    playsInline
    controls
    width={3840}
    height={1084}
  />
</Frame>

### Tool approval

Agent asks for approval before using MCP tools by default. Click the arrow next to the tool name to see arguments.

<Image
  height={902}
  width={1212}
  lightSrc="/docs-static/images/context/mcp/tool-confirm.png"
  alt="Tool confirmation prompt"
/>

#### Auto-run

Enable auto-run for Agent to use MCP tools without asking. Works like terminal commands. Read more about Auto-run settings [here](/docs/agent/tools#auto-run).

### Tool response

Cursor shows the response in chat with expandable views of arguments and responses:

<Image
  height={952}
  width={1212}
  lightSrc="/docs-static/images/context/mcp/tool-call.png"
  alt="MCP tool call result"
/>

### Images as context

MCP servers can return images - screenshots, diagrams, etc. Return them as base64 encoded strings:

```js
const RED_CIRCLE_BASE64 = "/9j/4AAQSkZJRgABAgEASABIAAD/2w...";
// ^ full base64 clipped for readability

server.tool("generate_image", async (params) => {
  return {
    content: [
      {
        type: "image",
        data: RED_CIRCLE_BASE64,
        mimeType: "image/jpeg",
      },
    ],
  };
});
```

See this [example server](https://github.com/msfeldstein/mcp-test-servers/blob/main/src/image-server.js) for implementation details. Cursor attaches returned images to the chat. If the model supports images, it analyzes them.

## Security considerations

When installing MCP servers, consider these security practices:

- **Verify the source**: Only install MCP servers from trusted developers and repositories
- **Review permissions**: Check what data and APIs the server will access
- **Limit API keys**: Use restricted API keys with minimal required permissions
- **Audit code**: For critical integrations, review the server's source code

Remember that MCP servers can access external services and execute code on your behalf. Always understand what a server does before installation.

## Real-world examples

For practical examples of MCP in action, see our [Web Development guide](/docs/cookbook/web-development) which demonstrates integrating Linear, Figma, and browser tools into your development workflow.

## FAQ

<AccordionGroup>
  <Accordion title="What's the point of MCP servers?">
    MCP servers connect Cursor to external tools like Google Drive, Notion, and
    other services to bring docs and requirements into your coding workflow.
  </Accordion>

<Accordion title="How do I debug MCP server issues?">
  View MCP logs by:

1. Open the Output panel in Cursor (<Kbd>Cmd+Shift+U</Kbd>)
2. Select "MCP Logs" from the dropdown
3. Check for connection errors, authentication issues, or server crashes

The logs show server initialization, tool calls, and error messages.

</Accordion>

<Accordion title="Can I temporarily disable an MCP server?">
  Yes! Toggle servers on/off without removing them:

1. Open Settings (<Kbd>Cmd+Shift+J</Kbd>)
2. Go to Features → Model Context Protocol
3. Click the toggle next to any server to enable/disable

Disabled servers won't load or appear in chat. This is useful for troubleshooting or reducing tool clutter.

</Accordion>

<Accordion title="What happens if an MCP server crashes or times out?">
  If an MCP server fails:

- Cursor shows an error message in chat
- The tool call is marked as failed
- You can retry the operation or check logs for details
- Other MCP servers continue working normally

Cursor isolates server failures to prevent one server from affecting others.

</Accordion>

<Accordion title="How do I update an MCP server?">
  For npm-based servers:

1. Remove the server from settings
2. Clear npm cache: `npm cache clean --force`
3. Re-add the server to get the latest version

For custom servers, update your local files and restart Cursor.

</Accordion>

  <Accordion title="Can I use MCP servers with sensitive data?">
    Yes, but follow security best practices:

    - Use environment variables for secrets, never hardcode them
    - Run sensitive servers locally with `stdio` transport
    - Limit API key permissions to minimum required
    - Review server code before connecting to sensitive systems
    - Consider running servers in isolated environments

  </Accordion>
</AccordionGroup>