# Configuring MCP Servers for Cursor SDK Integrations: Local and Cloud Setup Guide

> Learn to configure MCP servers for Cursor SDK integrations. This guide covers local and cloud setups for extending AI agents with tools like filesystems and GitHub.

- Repository: [Cursor/plugins](https://github.com/cursor/plugins)
- Tags: how-to-guide
- Published: 2026-05-25

---

**The Cursor SDK (`@cursor/sdk`) enables you to extend AI agents running locally or in Cursor's cloud environment by registering MCP (Model Context Protocol) servers via `stdio` subprocesses or `HTTP/SSE` endpoints, granting agents access to external tools like filesystems, GitHub, and Linear.**

The `@cursor/sdk` package, documented in the `cursor-sdk` directory of the `cursor/plugins` repository, provides a runtime-agnostic interface for agent execution. When configuring MCP servers for Cursor SDK integrations, you connect your agents to external capabilities through the standardized protocol defined in [`cursor-sdk/skills/cursor-sdk/references/mcp.md`](https://github.com/cursor/plugins/blob/main/cursor-sdk/skills/cursor-sdk/references/mcp.md).

## Architecture Overview

The Cursor SDK architecture separates the agent runtime from tool execution through three core components:

**Agent**: The core runner implemented in `@cursor/sdk` that communicates with the Cursor backend or local executor. You instantiate agents using `Agent.create()` or resume existing ones with `Agent.resume()`.

**MCP Server**: An HTTP or stdio service implementing the Model Context Protocol tool API. The SDK registers these under the `mcpServers` configuration key and forwards tool calls to the appropriate server.

**Transport Layer**: Defines how the SDK communicates with MCP servers. The `McpServerConfig` type supports two transport modes:

- **`stdio`**: Spawns a child process for local execution
- **`http`** or **`sse`**: Connects to REST-style endpoints for remote services

## Transport Configuration Types

According to the type definition in the Cursor SDK source, `McpServerConfig` accepts two distinct configuration shapes:

```typescript
type McpServerConfig =
  | { type?: "stdio"; command: string; args?: string[]; env?: Record<string,string>; cwd?: string }
  | { type?: "http" | "sse"; url: string; headers?: Record<string,string>;
      auth?: { CLIENT_ID: string; CLIENT_SECRET?: string; scopes?: string[] } };

```

**Stdio transport** requires a `command` string with optional `args`, `env` variables, and `cwd` directory. **HTTP/SSE transport** requires a `url` with optional `headers` for authentication and an `auth` object for OAuth flows, with detailed auth patterns documented in [`cursor-sdk/skills/cursor-sdk/references/auth.md`](https://github.com/cursor/plugins/blob/main/cursor-sdk/skills/cursor-sdk/references/auth.md).

## Local Runtime Configuration

When running agents locally via `Agent.create({ local: { cwd: process.cwd() } })`, the SDK spawns MCP servers on your machine using the local environment.

### Local Stdio Configuration

For filesystem access or local tooling, use the `stdio` transport to spawn subprocesses:

```typescript
import { Agent } from "@cursor/sdk";

const agent = Agent.create({
  apiKey: process.env.CURSOR_API_KEY!,
  model: { id: "composer-2" },
  local: { cwd: process.cwd() },
  mcpServers: {
    filesystem: {
      type: "stdio",
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-filesystem", process.cwd()],
      cwd: process.cwd(),
      env: { NODE_OPTIONS: "--max-old-space-size=4096" },
    },
  },
});

```

This configuration spawns the filesystem MCP server as a child process, passing the current working directory and Node.js memory options.

### Local HTTP Configuration

For services exposing MCP endpoints directly, configure `http` or `sse` transport:

```typescript
const agent = Agent.create({
  apiKey: process.env.CURSOR_API_KEY!,
  model: { id: "composer-2" },
  local: { cwd: process.cwd() },
  mcpServers: {
    linear: {
      type: "http",
      url: "https://mcp.linear.app/sse",
      headers: { Authorization: `Bearer ${process.env.LINEAR_API_KEY!}` },
    },
  },
});

```

Local HTTP configurations send headers as-is with each request, making them visible only to your local process.

## Cloud Runtime Configuration

When deploying to Cursor's cloud infrastructure via `Agent.create({ cloud: { repos: [...] } })`, MCP servers run inside Cursor-hosted VMs with specific constraints.

### Cloud Stdio Configuration

Cloud stdio servers execute within the VM environment, where `cwd` is forbidden and secrets are injected via `env`:

```typescript
const agent = Agent.create({
  apiKey: process.env.CURSOR_API_KEY!,
  model: { id: "composer-2" },
  cloud: {
    repos: [{ url: "https://github.com/your-org/your-repo", startingRef: "main" }],
  },
  mcpServers: {
    github: {
      type: "stdio",
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-github"],
      env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN! },
    },
  },
});

```

Note that command resolution in the cloud requires binaries to exist in the standard Linux image (`npx`, `node`, etc.). Omitting the `cwd` property is mandatory for cloud stdio configurations—setting it results in a `ConfigurationError`.

### Cloud HTTP Configuration

HTTP-based MCP servers in cloud mode have their headers forwarded by the Cursor backend, with values redacted from logs for security:

```typescript
const agent = Agent.create({
  apiKey: process.env.CURSOR_API_KEY!,
  model: { id: "composer-2" },
  cloud: { repos: [{ url: "https://github.com/your-org/your-repo", startingRef: "main" }] },
  mcpServers: {
    linear: {
      type: "http",
      url: "https://mcp.linear.app/sse",
      headers: { Authorization: `Bearer ${process.env.LINEAR_API_KEY!}` },
    },
  },
});

```

The backend proxies these headers, making the `Authorization` header case-sensitive—mis-spelling it causes authentication failures.

## Loading Ambient MCP Configuration

By default, the local SDK ignores project or user configuration files ([`.cursor/mcp.json`](https://github.com/cursor/plugins/blob/main/.cursor/mcp.json)). To enable ambient configuration loading, specify `settingSources` in your local configuration:

```typescript
const agent = Agent.create({
  apiKey: process.env.CURSOR_API_KEY!,
  local: {
    cwd: process.cwd(),
    settingSources: ["project", "user"],
  },
  // ...
});

```

After modifying [`.cursor/mcp.json`](https://github.com/cursor/plugins/blob/main/.cursor/mcp.json), reload the configuration without restarting the agent:

```typescript
await agent.reload();

```

This method, documented in [`cursor-sdk/skills/cursor-sdk/references/mcp.md`](https://github.com/cursor/plugins/blob/main/cursor-sdk/skills/cursor-sdk/references/mcp.md), picks up new ambient configurations for subsequent tool calls.

## Agent Persistence and Resumption

When resuming cloud agents with `Agent.resume()`, inline `mcpServers` configurations are **not persisted** across sessions. You must explicitly re-supply the MCP configuration:

```typescript
const baseMcp = {
  filesystem: { type: "stdio", command: "npx", args: ["-y", "@modelcontextprotocol/server-filesystem"] },
  linear: { type: "http", url: "https://mcp.linear.app/sse", headers: { Authorization: "Bearer ..." } },
};

const agent = Agent.resume(previousAgentId, {
  apiKey: process.env.CURSOR_API_KEY!,
  model: { id: "composer-2" },
  cloud: { repos: [{ url: "https://github.com/your-org/your-repo", startingRef: "main" }] },
  mcpServers: baseMcp,
});

```

Dashboard-configured servers, configured through the Cursor web interface, are persisted automatically and do not require re-registration.

## Critical Configuration Differences

Understanding the runtime divergence is essential for stable deployments:

- **Header Handling**: Local sends headers directly; cloud proxies through the backend with redaction
- **Environment Variables**: Local env is process-visible only; cloud env is injected into the VM and visible to all processes
- **Command Resolution**: Local uses your machine's `PATH`; cloud requires standard Linux image binaries
- **Working Directory**: Local supports `cwd`; cloud stdio forbids it entirely

## Common Configuration Pitfalls

Avoid these specific errors when configuring MCP servers for Cursor SDK integrations:

- **Including `cwd` in cloud stdio configs**: This triggers a `ConfigurationError` immediately
- **Case-sensitive headers in cloud**: The `Authorization` header must be capitalized correctly when using HTTP transport
- **Missing MCP configs on resume**: Always pass `mcpServers` when calling `Agent.resume()` in cloud mode
- **Custom binaries in cloud**: Ensure any non-standard binary exists in the cloud VM image or use `npx` to fetch it

## Summary

- **Cursor SDK** (`@cursor/sdk`) supports MCP servers via `stdio` and `HTTP/SSE` transports for both local and cloud runtimes
- **Local mode** spawns processes on your machine with full `cwd` and `PATH` access; headers are sent unmodified
- **Cloud mode** runs servers in Cursor-hosted VMs where `cwd` is forbidden and headers are proxied with redacted values in logs
- **Configuration persistence**: Inline `mcpServers` must be re-supplied when calling `Agent.resume()` in cloud; dashboard configs persist automatically
- **Ambient loading**: Enable `settingSources` in local mode to load [`.cursor/mcp.json`](https://github.com/cursor/plugins/blob/main/.cursor/mcp.json) files, using `agent.reload()` to refresh
- **Reference documentation**: Complete configuration details live in [`cursor-sdk/skills/cursor-sdk/references/mcp.md`](https://github.com/cursor/plugins/blob/main/cursor-sdk/skills/cursor-sdk/references/mcp.md)

## Frequently Asked Questions

### What is the difference between stdio and HTTP transport for MCP servers in Cursor SDK?

**Stdio transport** spawns the MCP server as a local subprocess, communicating over standard input/output streams. This is ideal for local filesystem access or tools requiring direct machine interaction. **HTTP/SSE transport** connects to running services via REST endpoints, suitable for cloud-hosted APIs like Linear or GitHub that already expose MCP-compatible endpoints. Cloud runtime stdio servers run inside the Cursor VM, while HTTP servers are called from the VM to external URLs.

### Why does my cloud stdio MCP configuration throw a ConfigurationError?

The Cursor cloud runtime explicitly forbids the `cwd` property in stdio configurations. When running in cloud mode, MCP servers must use binaries available in the standard Linux image (like `npx` or `node`), and the working directory is managed by the cloud environment. Remove the `cwd` key from your `McpServerConfig` to resolve this error.

### How do I persist MCP server configurations when resuming a cloud agent?

Inline `mcpServers` configurations passed to `Agent.create()` are **not persisted** when you resume a cloud agent using `Agent.resume()`. You must explicitly include the `mcpServers` object in the options passed to `Agent.resume()`. Alternatively, configure your MCP servers through the Cursor Dashboard (web interface), which stores configurations server-side and automatically attaches them to resumed agents.

### Can I use local [`.cursor/mcp.json`](https://github.com/cursor/plugins/blob/main/.cursor/mcp.json) configuration files with the Cursor SDK?

By default, the SDK ignores ambient configuration files. To enable loading from [`.cursor/mcp.json`](https://github.com/cursor/plugins/blob/main/.cursor/mcp.json) or user settings, set `settingSources: ["project", "user"]` (or `"all"`) in your local runtime configuration. After modifying the JSON file, call `await agent.reload()` to pick up changes without restarting the agent process. This feature is documented in [`cursor-sdk/skills/cursor-sdk/references/mcp.md`](https://github.com/cursor/plugins/blob/main/cursor-sdk/skills/cursor-sdk/references/mcp.md) and only applies to local runtimes.