How do I use cursor-sdk-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@cursor-sdk-mcp run a cursor agent to add error handling to src/api.ts" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

cursor-sdk-mcp

by newxun

Overview Schema Related Servers Score Discussions

TypeScript

Local

cursor-sdk-mcp

An MCP (Model Context Protocol) server that lets MCP clients such as Claude Code invoke the Cursor SDK and use Cursor Agent capabilities as tools for local and cloud coding workflows.

What it does

The server speaks MCP over stdio and exposes these tools:

Tool	Description
`cursor_whoami`	Verify the configured Cursor API key and return the authenticated identity.
`cursor_list_models`	List the Cursor models available to the account.
`cursor_run_agent`	Compatibility alias for a local Cursor Agent run against one `cwd`.
`cursor_run_local_agent`	Run a local Cursor Agent against one or more working directories with optional Cursor MCP settings, inline MCP servers, subagents, sandboxing, and auto-review.
`cursor_run_cloud_agent`	Run a Cursor Cloud Agent in a Cursor-hosted or self-hosted environment, optionally cloning repos and creating PRs.
`cursor_follow_up`	Continue a previous agent conversation by `agentId`.
`cursor_get_agent`	Fetch agent metadata.
`cursor_list_runs`	List runs for an agent.
`cursor_get_run`	Fetch one run by `runId`.
`cursor_cancel_run`	Cancel one run by `runId`.
`cursor_list_artifacts`	List artifacts produced by an agent.
`cursor_download_artifact`	Download an artifact as base64 content.

Under the hood it uses @cursor/sdk's local and cloud runtimes. Local agents read/write files on disk from this Node process. Cloud agents run in Cursor-hosted or self-hosted environments and can use Cursor account/team MCP configuration from cursor.com/agents.

Related MCP server: cursor-mcp-server

Requirements

Node.js >= 22.13 (required by @cursor/sdk).
A Cursor API key. Create one at the Cursor Dashboard → API Keys (user key) or Team settings (service account key).

Install & build

npm install
npm run build

Configure

Set your API key (see .env.example):

export CURSOR_API_KEY="your-cursor-api-key"
# Optional: default model id used when a tool call omits one (default: "auto")
export CURSOR_MCP_DEFAULT_MODEL="auto"

Use with Claude Code

claude mcp add cursor-sdk -- node /absolute/path/to/cursor-sdk-mcp/dist/index.js

Or add it to your MCP client config manually:

{
  "mcpServers": {
    "cursor-sdk": {
      "command": "node",
      "args": ["/absolute/path/to/cursor-sdk-mcp/dist/index.js"],
      "env": { "CURSOR_API_KEY": "your-cursor-api-key" }
    }
  }
}

Then ask Claude Code to, for example, "use the cursor agent to refactor src/auth.ts", and it will call cursor_run_local_agent or the compatibility cursor_run_agent.

Local agent usage

Use cursor_run_local_agent when the agent should work in local directories:

{
  "prompt": "Refactor src/server.ts to split schemas into src/schemas.ts and run tests.",
  "cwd": "/absolute/path/to/repo",
  "model": "auto",
  "mode": "agent",
  "settingSources": ["project", "user", "plugins"],
  "autoReview": true
}

settingSources controls which Cursor MCP/settings layers the local runtime loads from disk. You can also pass inline mcpServers, agents, and sandboxOptions for one-off tool wiring and safety. For local cursor_follow_up, lifecycle, and artifact calls, pass the same cwd used to create the agent so the SDK can find persisted local agent state.

Live progress and cancellation

cursor_run_agent, cursor_run_local_agent, cursor_run_cloud_agent, and cursor_follow_up run to completion in a single tool call. Because a real coding run can take minutes, the server keeps the call responsive:

Progress streaming. When the MCP client sends a progressToken with the request (most clients do this automatically when you register a progress callback), the server streams each agent step — assistant text, tool calls, status changes — back as notifications/progress. Clients that reset their request timeout on progress (set resetTimeoutOnProgress) won't time out on long runs, and the user sees what the agent is doing instead of a silent wait.
Cancellation. If the client cancels the tool call (its AbortSignal fires), the server cancels the underlying Cursor run, so you stop paying for work you no longer need.

Progress streaming is best-effort: if a client doesn't request progress, or the runtime doesn't support streaming, the tool still returns the same final result.

Cloud agent usage

Use cursor_run_cloud_agent when the agent should run in Cursor Cloud:

{
  "prompt": "Add tests for the auth middleware and open a PR.",
  "repos": [{ "url": "https://github.com/your-org/your-repo", "startingRef": "main" }],
  "model": "auto",
  "autoCreatePR": true
}

repos can be omitted for an empty workspace or a named cloud environment. Cloud agents can use inline MCP plus Cursor account/team MCP configured at cursor.com/agents. Use the lifecycle tools to inspect runs, cancel work, and fetch artifacts.

Cursor MCP and skills strategy

Local agents use inline MCP unless settingSources includes project, user, or plugin settings.
Local stdio MCP servers may include cwd; cloud stdio MCP servers must not include cwd.
Cloud agents use inline MCP plus user/team MCP from cursor.com/agents.
OAuth MCP must already be authorized in Cursor before local reuse.
Cursor skills can live in .cursor/skills/, .agents/skills/, ~/.cursor/skills/, or ~/.agents/skills/.
Claude Code skills are separate from this integration and are not loaded by Cursor Agent through this MCP server.

Development

npm run dev        # run from source with hot reload (tsx)
npm run typecheck  # type-check only
npm run lint       # eslint
npm test           # integration tests (fake Cursor backend, no network)
npm run demo       # spawn the built server over stdio and call its tools
RUN_AGENT=1 npm run demo   # additionally run a real Cursor Agent (needs CURSOR_API_KEY)

How it's structured

src/cursor.ts — CursorService interface + CursorSdkService (the @cursor/sdk wrapper).
src/server.ts — builds the McpServer and registers the tools. Decoupled from the SDK via CursorService so tests can inject a fake backend.
src/index.ts — entry point; wires the real service to a StdioServerTransport.
tests/server.test.ts — connects an in-memory MCP client to the server and exercises every tool.
examples/demo-client.ts — end-to-end demo over a real stdio transport.

License

MIT

Available Tools

4 tools

cursor_follow_upCursor: follow upA

Destructive

Continue an existing Cursor Agent conversation by agentId with a new prompt. Conversation context from previous runs is loaded automatically.

ParametersJSON Schema

Name	Required	Description
`agentId`	Yes	The agentId returned by a previous cursor_run_agent call.
`prompt`	Yes	Follow-up instruction for the agent.
`model`	No	Optional per-run model override.

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide destructiveHint=true; description adds automatic context loading. Additional behavioral details like mutation effects are omitted.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with zero waste, front-loading the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema provided and description lacks return value details. Adequate for simple follow-up but incomplete for understanding full tool behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers 100% of parameters with descriptions. Description adds no further meaning beyond restating schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it continues an existing conversation via agentId with a new prompt, distinguishing it from sibling cursor_run_agent which starts new conversations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies use after cursor_run_agent by requiring agentId. Provides context but no explicit when-not-to-use alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

cursor_list_modelsCursor: list modelsA

Read-only

List the Cursor models available to the configured account. Use the returned ids as the model argument for cursor_run_agent / cursor_follow_up.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint and openWorldHint, so the description's main addition is the usage of returned ids. It confirms the read-only nature but does not disclose further behavioral traits like pagination or result format. Adequate given annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core purpose, and every word adds value. No wasted text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter list tool with strong annotations, the description is complete. It explains the output's purpose (model ids for sibling tools) and the scope (available to account). No gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has zero parameters with 100% coverage, so the description does not need to add parameter details. The description provides no param info, which is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists Cursor models available to the configured account, with a specific verb ('List') and resource ('Cursor models'). It distinguishes from siblings by explaining how the returned ids are used with cursor_run_agent and cursor_follow_up.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly tells the agent to use returned model ids as the `model` argument for two sibling tools, providing clear context. It does not include when-not-to-use or alternative tools, but the guidance is strong.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

cursor_run_agentCursor: run agentA

Destructive

Run a Cursor Agent (local runtime) against a working directory and return the final result. The agent can read, edit, and write files and run shell commands in cwd. Returns an agentId you can pass to cursor_follow_up to continue the same conversation.

ParametersJSON Schema

Name	Required	Description
`prompt`	Yes	Instruction for the Cursor Agent.
`cwd`	Yes	Absolute path to the working directory the agent operates in.
`model`	No	Model id (e.g. "composer-2.5"). Defaults to the server default ("auto").
`mode`	No	"agent" implements changes directly; "plan" explores and plans first.

TDQS

A4.2/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Description aligns with annotations: confirms destructive hint via file write/shell commands, open-world hint via flexibility. Adds agentId follow-up detail. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences: first sentence states purpose, second adds capabilities and follow-up. No extraneous words, efficient structure.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Description covers what the agent does and follow-up reference. No output schema, so mention of agentId is helpful. Could elaborate on return format, but sufficient for selection.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so description does not need to add param details. Description provides operational context but does not enhance individual parameter meaning beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states verb 'run', resource 'Cursor Agent', and scope 'against a working directory'. Distinguishes from sibling tools by mentioning cursor_follow_up for continuation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides some context by listing agent capabilities (read, edit, write files, run commands) but does not explicitly state when to use this tool versus alternatives or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

cursor_whoamiCursor: who am IA

Read-only

Verify the configured Cursor API key and return the authenticated account identity. Use this first to confirm authentication works before running an agent.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint=true and openWorldHint=true, so the description does not need to disclose destructive behavior. It adds value by clarifying that the tool verifies the key and returns identity, which is consistent with the annotations. No contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long, directly to the point, and front-loaded with the purpose. No extraneous words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple authentication check tool with no parameters and no output schema, the description is fully complete. It explains what it does and when to use it, covering all needed context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has no parameters, and schema coverage is 100%. Baseline is 4 for 0 parameters. The description adds context about the return value (account identity), which is helpful beyond the empty schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool verifies the Cursor API key and returns the authenticated account identity, which is a specific verb-resource pair. It distinguishes itself from sibling tools like cursor_run_agent and cursor_list_models by focusing on authentication verification.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description directly advises to use this tool 'first to confirm authentication works before running an agent', providing explicit guidance on when to use it and implying not to use it for other purposes.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

4 tool updatesv0.1.0Jun 23, 2026
- First observedcursor_follow_up
- First observedcursor_list_models
- First observedcursor_run_agent
- First observedcursor_whoami

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.3/5.0

Disambiguation5/5

Each tool serves a distinct purpose: authentication, model listing, starting an agent, and continuing a conversation. No overlap.

Naming Consistency5/5

All tools use snake_case with a consistent 'cursor_' prefix and action-oriented verbs, forming a predictable pattern.

Tool Count5/5

With 4 tools, the set covers the essential interactions (auth, model list, run, follow-up) without bloat or gaps.

Completeness4/5

The domain is well-covered for basic usage; missing an optional stop/status tool, but core workflows are complete.

Maintenance

ActivityStale

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Agent Router C
io.github.Tim-Projekt
Discover and call AI agents via MCP. Supports A2A agents and platform agents with async tasks.
Agent Orchestration Autonomous Agents
252
RogerRat A
io.github.opcastil11
Real-time chat hub for AI agents — Claude Code, Cursor, Cline, Codex over MCP or REST.
Communication Agent Orchestration
21
Apuchat A
io.github.opcastil11
Real-time chat for AI agents. Claude Code, Cursor, Cline and Codex join channels over MCP.
Communication Agent Orchestration
181
Camber - Remote Agentic Data Science AOAuth
com.cambercloud.camber-mcp
Remote data science agents for Snowflake, Databricks & BigQuery in Claude/Cursor via MCP
AI & Machine Learning Data Platforms
2

Related MCP Servers

@willpowell8/cursor-cloud
Coding Agents Developer Tools Version Control
willpowell8
A
license
Not graded
quality
C
maintenance
Enables programmatic control of Cursor's cloud-based AI agents for automated code generation and repository management via standardized MCP tools.
Updated 8 months ago (2026-01-05 20:14 UTC)
25
6
MIT
cursor-mcp-server
Coding Agents Command Line
bbarney7
F
license
Not graded
quality
D
maintenance
An MCP server wrapping the Cursor CLI agent, enabling Claude Code and other MCP clients to delegate tasks to Cursor's AI agent for file writing, bash commands, and codebase queries.
Updated 8 months ago (2026-01-20 14:53 UTC)
-
cursor-agent-bridge
Coding Agents Developer Tools Code Execution
cybas
A
license
Not graded
quality
B
maintenance
Enables MCP clients like Claude Code to delegate coding tasks to the local Cursor Agent CLI, with persistent per-workspace sessions that resume across calls.
Updated a month ago (2026-08-11 08:15 UTC)
12
MIT
cursor_worker
Coding Agents File Systems Shell Access
yuusuke1024
F
license
Not graded
quality
B
maintenance
Bridges MCP to Cursor Agent via ACP, allowing Codex to delegate file edits and shell commands to Cursor for repository modifications, with security defaults.
Updated a month ago (2026-08-02 15:31 UTC)
-

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/newxun/cursor-sdk-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server