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

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.

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:

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.

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:

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:

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:

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:

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). To enable ambient configuration loading, specify settingSources in your local configuration:

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

After modifying .cursor/mcp.json, reload the configuration without restarting the agent:

await agent.reload();

This method, documented in 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:

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 files, using agent.reload() to refresh
• Reference documentation: Complete configuration details live in 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 configuration files with the Cursor SDK?

By default, the SDK ignores ambient configuration files. To enable loading from .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 and only applies to local runtimes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}