Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Cursor Agent MCP Server analyze the authentication middleware and suggest improvements"
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.
Minimal, hardened Model Context Protocol (MCP) server that wraps the cursor-agent CLI and exposes multiple, Claude‑friendly tools for chat, repository analysis, code search, planning, and more.
Core implementation: cursor-agent-mcp/server.js Test harness: cursor-agent-mcp/test_client.mjs Package manifest: cursor-agent-mcp/package.json
This MCP exists to offload heavy “thinking” and repo‑aware tasks from the host (e.g., Claude Code) to the cursor-agent CLI. By letting the CLI handle analysis/planning/search with focused, prompt‑based instructions, you can:
Scope work to only the needed files/paths instead of streaming the entire workspace.
Choose a cost‑effective model via environment (or per call) and keep the host’s context small.
Control response verbosity through output_format ("text" | "markdown" | "json") and tailored prompts.
Use specialized tools (analyze, search, plan, edit) that produce targeted outputs rather than general chat.
Prefer precise scopes:
Use include/exclude globs with cursor_agent_search_repo and curated paths for cursor_agent_analyze_files.
Pick output formats intentionally:
Use "text" or "markdown" for concise answers. Reserve "json" only when you truly need structured output (it’s usually larger).
Select a model that matches the task:
Set CURSOR_AGENT_MODEL to a cost‑effective default; override per tool call only when necessary.
Avoid unnecessary echo/debug:
CURSOR_AGENT_ECHO_PROMPT=1 is helpful during setup, but disables it later to save tokens in host logs.
Keep DEBUG_CURSOR_MCP off in normal use; it writes diagnostics to stderr (not counted in host tokens, but noisy).
Control runtime instead of idle‑kill:
Keep CURSOR_AGENT_IDLE_EXIT_MS="0" so valid runs aren’t cut mid‑generation. Bound cost/time with CURSOR_AGENT_TIMEOUT_MS and focused prompts.
Use cursor_agent_raw thoughtfully:
It’s powerful and can stream detailed sessions; for cheapest usage, prefer the focused tools with concise prompts and "text" output.
Related MCP server: Cursor Agent MCP Server
Multi‑tool surface modeled after “verb-centric” CLIs
Works well in Claude Code and other MCP hosts
Safe process spawn (no shell), robust timeout handling
Optional prompt echoing for easy debugging inside hosts
Configurable defaults via environment variables (model, force, timeouts, executable path)
Backward‑compatible legacy tool for single‑shot chat
Node.js 18+ (tested up to Node 22)
A working cursor-agent CLI in your PATH or at an explicit location
Provider credentials configured for your chosen model (e.g., via the CLI’s own mechanism)
Clone or download this repository.
Install dependencies for the MCP server:
cd ./cursor-agent-mcp
npm ci # or: npm installEnsure the cursor-agent CLI is installed and on PATH (or set CURSOR_AGENT_PATH):
cursor-agent --versionRun the MCP server:
# from the server directory
node ./server.js
# or from the repo root using the provided script
npm --prefix ./cursor-agent-mcp run startNo. This server runs directly from the repository and is not published to npm (package.json sets "private": true). Use Node to execute server.js after installing dependencies as shown above.
If you later publish this as an npm package and add a bin entry in package.json, you could run it with npx and point your MCP host to that executable instead. Until then, prefer the Node-based command shown here.
A tiny client is provided to list tools and call one of them over stdio:
# list tools and call chat with a prompt
node ./cursor-agent-mcp/test_client.mjs "Hello from smoke test"
# run the raw tool with --help (no implicit --print)
TEST_TOOL=cursor_agent_raw TEST_ARGV='["--help"]' node ./cursor-agent-mcp/test_client.mjsThe client uses the same stdio transport a host would use. See JavaScript.main().
All tool calls ultimately invoke the same executor JavaScript.invokeCursorAgent(), which:
Resolves the cursor-agent executable (explicit path or PATH)
Injects --print and --output-format <fmt> by default
Optionally adds -m <model> and -f based on env/args
Streams stdout/stderr and enforces a total timeout
Optionally kills long‑idle processes (disabled by default)
The legacy wrapper JavaScript.runCursorAgent() accepts a prompt and optional flags, composing the argv and delegating to the executor.
These tools are registered in JavaScript.server.tool() and below. All tools share the “COMMON” arguments:
output_format: "text" | "json" | "markdown" (default "text")
extra_args?: string[]
cwd?: string
executable?: string
model?: string
force?: boolean
echo_prompt?: boolean → prepend “Prompt used: …” to the result
Args: { prompt: string, ...COMMON }
Behavior: Single‑shot chat by passing the prompt as the final positional argument.
Code path: JavaScript.server.tool() → JavaScript.runCursorAgent()
Example:
{
"name": "cursor_agent_chat",
"arguments": { "prompt": "Explain SIMD in one paragraph", "output_format": "markdown" }
}Args: { file: string, instruction: string, apply?: boolean, dry_run?: boolean, prompt?: string, ...COMMON }
Behavior: Prompt‑based wrapper. Builds a structured instruction that asks the agent to edit or propose a patch for the file.
Code path: JavaScript.server.tool()
Example:
{
"name": "cursor_agent_edit_file",
"arguments": {
"file": "src/app.ts",
"instruction": "Extract the HTTP client into a separate module and add retries",
"dry_run": true,
"output_format": "markdown"
}
}Args: { paths: string | string[], prompt?: string, ...COMMON }
Behavior: Prompt‑based repository/file analysis listing the paths to focus on.
Code path: JavaScript.server.tool()
Example:
{
"name": "cursor_agent_analyze_files",
"arguments": {
"paths": ["src", "scripts"],
"prompt": "Give me a concise architecture overview with module boundaries"
}
}Args: { query: string, include?: string | string[], exclude?: string | string[], ...COMMON }
Behavior: Prompt‑based code search over the repo, with optional include/exclude globs.
Code path: JavaScript.server.tool()
Example:
{
"name": "cursor_agent_search_repo",
"arguments": {
"query": "fetch(",
"include": ["src/**/*.ts", "app/**/*.tsx"],
"exclude": ["node_modules/**", "dist/**"],
"output_format": "markdown",
"echo_prompt": true
}
}Args: { goal: string, constraints?: string[], ...COMMON }
Behavior: Prompt‑based planning tool that returns a numbered plan for your goal.
Code path: JavaScript.server.tool()
Example:
{
"name": "cursor_agent_plan_task",
"arguments": {
"goal": "Set up CI to lint and test this repo",
"constraints": ["GitHub Actions", "Node 18"]
}
}Args: { argv: string[], print?: boolean, ...COMMON }
Behavior: Forwards raw argv to the CLI. Defaults to print=false to avoid adding --print; set print=true to inject it.
Code path: JavaScript.server.tool()
Examples:
{ "name": "cursor_agent_raw", "arguments": { "argv": ["--help"], "print": false } }{ "name": "cursor_agent_raw", "arguments": { "argv": ["-m","gpt-5","What is SIMD?"], "print": true } }Args: { prompt: string, ...COMMON }
Behavior: Original single‑shot chat wrapper; maintained for compatibility.
Code path: JavaScript.server.tool()
Example Claude Code/Claude Desktop entry:
{
"mcpServers": {
"cursor-agent": {
"command": "node",
"args": ["/abs/path/to/cursor-agent-mcp/server.js"],
"env": {
"CURSOR_AGENT_ECHO_PROMPT": "1",
"CURSOR_AGENT_FORCE": "true",
"CURSOR_AGENT_PATH": "/home/you/.local/bin/cursor-agent",
"CURSOR_AGENT_MODEL": "gpt-5",
"CURSOR_AGENT_IDLE_EXIT_MS": "0",
"CURSOR_AGENT_TIMEOUT_MS": "60000"
}
}
}
}Add DEBUG_CURSOR_MCP=1 to print diagnostics to stderr (spawn argv, prompt preview, exit). Useful while integrating or troubleshooting.
{
"mcpServers": {
"cursor-agent": {
"command": "node",
"args": ["/abs/path/to/cursor-agent-mcp/server.js"],
"env": {
"CURSOR_AGENT_ECHO_PROMPT": "1",
"CURSOR_AGENT_FORCE": "true",
"CURSOR_AGENT_PATH": "/home/you/.local/bin/cursor-agent",
"CURSOR_AGENT_MODEL": "gpt-5",
"CURSOR_AGENT_IDLE_EXIT_MS": "0",
"CURSOR_AGENT_TIMEOUT_MS": "60000",
"DEBUG_CURSOR_MCP": "1"
}
}
}
}Note: many hosts don’t display server stderr logs. To see the effective prompt in the UI, use CURSOR_AGENT_ECHO_PROMPT=1 or pass "echo_prompt": true in tool arguments. Implementation points:
debug spawn/exit logs: JavaScript.invokeCursorAgent()
prompt preview: JavaScript.runCursorAgent()
Environment variables understood by the server:
CURSOR_AGENT_PATH: absolute path to the cursor-agent binary; falls back to PATH
CURSOR_AGENT_MODEL: default model (appended as -m <model> unless you already provided one)
CURSOR_AGENT_FORCE: "true"/"1" to inject -f unless already present
CURSOR_AGENT_TIMEOUT_MS: hard runtime ceiling (default 30000)
CURSOR_AGENT_IDLE_EXIT_MS: idle‑kill threshold in ms; "0" disables idle kill (recommended)
CURSOR_AGENT_ECHO_PROMPT: "1" to prepend the effective prompt to the tool’s result
DEBUG_CURSOR_MCP: "1" to log spawn/exit diagnostics to stderr
Call any of the tools described above; arguments map 1:1 to the JSON fields in “Tools” section.
To see the exact prompt, either set CURSOR_AGENT_ECHO_PROMPT=1 globally or pass "echo_prompt": true in the tool call.
For advanced use, prefer cursor_agent_raw for precise control of argv and print behavior.
“cursor-agent not found”
Set CURSOR_AGENT_PATH to the absolute path of the CLI or ensure it’s on PATH.
“No prompt provided for print mode”
You called RAW with print=true but without a prompt. Either provide a prompt in argv or set print=false.
Premature termination mid‑generation
Increase CURSOR_AGENT_TIMEOUT_MS, and keep CURSOR_AGENT_IDLE_EXIT_MS at "0".
Empty tool output
Verify provider credentials and model name. Try cursor_agent_raw with argv: ["--version"] to confirm CLI health.
Start the server directly:
node ./cursor-agent-mcp/server.js
Smoke client:
node ./cursor-agent-mcp/test_client.mjs "hello"
TEST_TOOL=cursor_agent_raw TEST_ARGV='["--help"]' node ./cursor-agent-mcp/test_client.mjs
Useful env while developing:
DEBUG_CURSOR_MCP=1 CURSOR_AGENT_ECHO_PROMPT=1
Key entry points:
Executor: JavaScript.invokeCursorAgent()
Legacy runner: JavaScript.runCursorAgent()
Tool registrations start at: JavaScript.server.tool()
Child processes are spawned with shell: false to avoid shell injection and quoting issues.
Inputs are validated with Zod; unknown types are rejected.
Avoid logging secrets; DEBUG only prints argv and minimal env context.
Current server version: 1.1.0 (see cursor-agent-mcp/package.json)
MIT (see cursor-agent-mcp/package.json)
MCP protocol and SDK by the Model Context Protocol team
Inspiration: multi‑verb MCP servers such as gemini‑mcp‑tool
Analyze one or more paths; optional prompt. Prompt-based wrapper.
| Name | Required | Description | Default |
|---|---|---|---|
| paths | Yes | ||
| prompt | No | ||
| output_format | No | text | |
| extra_args | No | ||
| cwd | No | ||
| executable | No | ||
| model | No | ||
| force | No | ||
| echo_prompt | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. The description mentions it's a 'Prompt-based wrapper' which hints at some LLM-based functionality, but doesn't explain what analysis actually entails, what permissions are needed, whether it modifies files, what the output looks like, or any rate limits. For a tool with 9 parameters and no annotation coverage, this leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at just two short phrases. While this could be considered under-specified rather than appropriately concise, the structure is front-loaded with the core purpose. There's no wasted language, though the brevity comes at the cost of completeness. The two phrases each serve a purpose: stating the action and hinting at implementation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 9 parameters, no annotations, no output schema, and 0% schema description coverage, the description is woefully incomplete. It doesn't explain what analysis means, what the tool actually does, what the output looks like, or how to use any of the parameters. The description provides only the barest minimum context for a complex multi-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage for 9 parameters, the description provides no information about any parameters. It doesn't explain what 'paths' should contain, what the 'prompt' should include, what 'extra_args' might be used for, or the purpose of parameters like 'cwd', 'executable', 'model', 'force', or 'echo_prompt'. The description fails to compensate for the complete lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool 'Analyze one or more paths; optional prompt' which provides a basic verb+resource combination, but it's vague about what 'analyze' means in this context. The phrase 'Prompt-based wrapper' adds some context but doesn't clearly differentiate this from sibling tools like cursor_agent_search_repo or cursor_agent_raw. The purpose is understandable but lacks specificity about the type of analysis performed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance about when to use this tool versus alternatives. There's no mention of when this analysis tool is appropriate versus cursor_agent_search_repo for searching or cursor_agent_edit_file for modifications. The description doesn't specify any prerequisites, constraints, or typical use cases that would help an agent decide when to invoke this particular tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Chat with cursor-agent using a prompt and optional model/force/output_format.
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | ||
| output_format | No | text | |
| extra_args | No | ||
| cwd | No | ||
| executable | No | ||
| model | No | ||
| force | No | ||
| echo_prompt | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but offers minimal behavioral insight. It mentions 'optional model/force/output_format' but doesn't explain what 'force' does, how the chat interacts with the agent, whether it's stateful, what authentication might be needed, or typical response patterns. For an 8-parameter tool with zero annotation coverage, this leaves significant gaps in understanding how the tool behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise - a single sentence that efficiently states the core functionality. Every word earns its place with no redundancy or unnecessary elaboration. It's front-loaded with the essential action and resource, making it easy to scan and understand at a glance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter tool with no annotations and no output schema, the description is inadequate. It doesn't explain what the tool returns, how errors are handled, what 'cursor-agent' represents, or how this differs from other chat interfaces. Given the complexity implied by multiple optional parameters and sibling tools, more context about the tool's role and behavior is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate but only mentions 'prompt and optional model/force/output_format' - covering just 4 of 8 parameters. It doesn't explain 'extra_args', 'cwd', 'executable', or 'echo_prompt', nor does it provide context for how parameters like 'model' or 'force' affect behavior. The description adds minimal value beyond the bare parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Chat') and resource ('cursor-agent'), specifying it uses a prompt with optional parameters. It distinguishes from siblings like 'cursor_agent_analyze_files' or 'cursor_agent_edit_file' by focusing on general chat interaction rather than file-specific operations. However, it doesn't explicitly differentiate from 'cursor_agent_raw' which might also involve chat-like functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'cursor_agent_plan_task' or 'cursor_agent_raw'. It mentions optional parameters but doesn't explain scenarios where this chat tool is preferred over other cursor-agent tools for similar tasks. There's no mention of prerequisites, constraints, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edit a file with an instruction. Prompt-based wrapper; no CLI subcommand required.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | ||
| instruction | Yes | ||
| apply | No | ||
| dry_run | No | ||
| prompt | No | ||
| output_format | No | text | |
| extra_args | No | ||
| cwd | No | ||
| executable | No | ||
| model | No | ||
| force | No | ||
| echo_prompt | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions being a 'Prompt-based wrapper' which suggests AI-driven editing rather than direct manipulation, but fails to describe critical behaviors: whether edits are destructive, authentication needs, rate limits, error handling, or what 'edit' actually does to the file. The mention of 'no CLI subcommand required' is helpful but insufficient for a tool with 12 parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately brief with two concise sentences that each add value: the first states the core function, the second provides implementation context. No wasted words, though it could be more front-loaded with clearer purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (12 parameters, 0% schema coverage, no annotations, no output schema), the description is severely incomplete. It doesn't explain what 'editing' means operationally, how parameters interact, what the tool returns, or error conditions. For a file manipulation tool with many configuration options, this leaves critical gaps for agent understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for all 12 parameters, and the description provides no information about any parameters beyond implying that 'instruction' is involved in editing. Parameters like 'apply', 'dry_run', 'model', 'force', and 'extra_args' remain completely unexplained, leaving the agent with no semantic understanding of what these inputs control.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool 'Edit a file with an instruction' which provides a basic verb+resource combination, but it's vague about what 'edit' entails and doesn't distinguish from siblings like cursor_agent_analyze_files or cursor_agent_raw. The additional note about being a 'Prompt-based wrapper' adds some context but doesn't fully clarify the specific editing mechanism.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives is provided. The description mentions 'no CLI subcommand required' which hints at convenience over raw execution, but doesn't specify scenarios where this wrapper is preferable to sibling tools like cursor_agent_run or cursor_agent_raw for file editing tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a plan for a goal with optional constraints. Prompt-based wrapper.
| Name | Required | Description | Default |
|---|---|---|---|
| goal | Yes | ||
| constraints | No | ||
| output_format | No | text | |
| extra_args | No | ||
| cwd | No | ||
| executable | No | ||
| model | No | ||
| force | No | ||
| echo_prompt | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but offers minimal behavioral insight. It mentions 'Prompt-based wrapper' which hints at LLM interaction but doesn't disclose critical traits like whether this is read-only, what permissions are needed, rate limits, or how plans are generated (e.g., step-by-step vs. high-level). For a tool with 9 parameters, this leaves significant gaps in understanding its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief (two phrases) but not effectively structured. The first phrase is clear but basic, while 'Prompt-based wrapper' is ambiguous and doesn't add useful context. It's concise but under-informative rather than efficiently packed with value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given high complexity (9 parameters, 0% schema coverage, no annotations, no output schema), the description is incomplete. It doesn't explain what the tool returns, how plans are structured, or the role of most parameters. For a planning tool in a set of agent-related tools, this leaves too many unknowns for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate but fails to do so. It mentions 'goal' and 'optional constraints' which map to two parameters, but ignores the other 7 parameters (output_format, extra_args, cwd, executable, model, force, echo_prompt). This leaves most parameters undocumented, severely limiting understanding of their purpose and usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Generate a plan for a goal with optional constraints' which provides a basic verb+resource combination, but it's vague about what kind of plan (e.g., code execution plan, project plan) and the 'Prompt-based wrapper' adds confusion rather than clarity. It doesn't distinguish this from sibling tools like cursor_agent_chat or cursor_agent_raw that might also involve planning.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There's no guidance on when to use this tool versus alternatives like cursor_agent_chat for discussion or cursor_agent_run for execution. The description mentions 'optional constraints' but doesn't explain what scenarios warrant using this tool over other planning or analysis tools in the sibling set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Advanced: provide raw argv array to pass after common flags (e.g., ["search","--query","foo"]).
| Name | Required | Description | Default |
|---|---|---|---|
| argv | Yes | ||
| No | |||
| output_format | No | text | |
| extra_args | No | ||
| cwd | No | ||
| executable | No | ||
| model | No | ||
| force | No | ||
| echo_prompt | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions 'Advanced' and provides an example, but doesn't explain what the tool actually does (e.g., executes a command, invokes an agent, returns output), what permissions or side effects are involved, or how errors are handled. For a tool with 9 parameters and no annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with an example, making it appropriately concise and front-loaded. However, it could be more structured by explicitly stating the tool's action and context. Every word earns its place, but the brevity contributes to underspecification rather than clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (9 parameters, no annotations, no output schema), the description is incomplete. It doesn't explain the tool's core functionality, how parameters interact, what the output looks like, or how it relates to sibling tools. The example helps but doesn't provide enough context for an agent to use the tool effectively without additional assumptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning none of the 9 parameters are documented in the schema. The description only mentions 'argv' with an example, ignoring the other 8 parameters (print, output_format, extra_args, cwd, executable, model, force, echo_prompt). This fails to compensate for the schema gap, leaving most parameters unexplained and their purposes unclear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool 'provide[s] raw argv array to pass after common flags' with an example, which gives a vague purpose of passing command-line arguments. However, it doesn't specify what tool or command these arguments are for, what 'common flags' refer to, or how this differs from sibling tools like cursor_agent_run. The description is functional but lacks specificity about the target resource or context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description mentions 'common flags' but doesn't explain what these are, when this raw approach is preferred over more structured sibling tools (e.g., cursor_agent_run), or any prerequisites. Usage is implied through the example but not explicitly stated, leaving the agent to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run cursor-agent with a prompt and desired output format (legacy single-shot).
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | ||
| output_format | No | text | |
| extra_args | No | ||
| cwd | No | ||
| executable | No | ||
| model | No | ||
| force | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions 'legacy single-shot' which hints at behavioral traits (single interaction vs. chat), but doesn't disclose critical details like what 'cursor-agent' does, whether it's read-only or mutating, authentication needs, rate limits, or what 'run' entails. The description is insufficient for a tool with 7 parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (one sentence) and front-loaded with the core action. However, it's arguably too brief given the tool's complexity, as it omits necessary context for understanding the tool's purpose and parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given high complexity (7 parameters, 0% schema coverage, no annotations, no output schema), the description is incomplete. It doesn't explain what 'cursor-agent' is, what 'run' does, the meaning of most parameters, or expected return values. The minimal information provided is inadequate for effective tool use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions 'prompt and desired output format', which covers only 2 of 7 parameters (prompt and output_format). It doesn't explain the semantics of extra_args, cwd, executable, model, or force, leaving most parameters undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool 'Run cursor-agent with a prompt and desired output format (legacy single-shot)', which provides a basic verb ('Run') and resource ('cursor-agent') but is vague about what 'cursor-agent' actually does. It distinguishes from some siblings by mentioning 'legacy single-shot', but doesn't clearly differentiate from all alternatives like 'cursor_agent_chat' or 'cursor_agent_raw'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides minimal guidance with 'legacy single-shot', implying this is an older or simpler version compared to other tools, but doesn't explicitly state when to use this vs. alternatives like 'cursor_agent_chat' or 'cursor_agent_plan_task'. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search repository code with include/exclude patterns. Prompt-based wrapper.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| include | No | ||
| exclude | No | ||
| output_format | No | text | |
| extra_args | No | ||
| cwd | No | ||
| executable | No | ||
| model | No | ||
| force | No | ||
| echo_prompt | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure but offers minimal information. It mentions 'Prompt-based wrapper' which hints at some AI/LLM interaction, but doesn't explain what this entails—such as whether it uses external APIs, has rate limits, requires authentication, or how it handles errors. For a tool with 10 parameters and no annotation coverage, this leaves critical behavioral traits undocumented.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with only two short phrases, making it front-loaded and efficient. However, the second phrase 'Prompt-based wrapper' is ambiguous and doesn't add clear value, slightly reducing its effectiveness. Overall, it avoids unnecessary verbosity but could be more informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of 10 parameters, 0% schema coverage, no annotations, and no output schema, the description is incomplete. It doesn't explain the tool's behavior, return values, error handling, or most parameter meanings. For a search tool with many configuration options, this leaves too many gaps for an agent to use it effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning none of the 10 parameters have descriptions in the schema. The tool description only vaguely references 'include/exclude patterns' and 'Prompt-based wrapper', which partially relates to 'include', 'exclude', and possibly 'model' or 'extra_args', but fails to explain most parameters like 'cwd', 'executable', 'force', 'echo_prompt', or the specifics of 'output_format'. This doesn't adequately compensate for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool 'Search repository code with include/exclude patterns' which provides a basic verb+resource combination, but it's vague about what 'Prompt-based wrapper' means and doesn't clearly distinguish this search functionality from potential sibling tools like cursor_agent_analyze_files or cursor_agent_raw. The purpose is understandable but lacks specificity about scope and differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives. The description doesn't mention any context, prerequisites, or exclusions, nor does it reference sibling tools. An agent would have to guess based on tool names alone, which is insufficient for informed selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The tools have some distinct purposes like analyze_files, edit_file, plan_task, and search_repo, but there is notable overlap between cursor_agent_chat and cursor_agent_run (both involve prompting the agent), and cursor_agent_raw is ambiguous as it could duplicate functionality of other tools. Descriptions help differentiate, but an agent might struggle to choose between chat and run for similar tasks.
All tool names follow a consistent snake_case pattern with the prefix 'cursor_agent_' followed by a verb or action (e.g., analyze_files, chat, edit_file). This uniformity makes the set predictable and easy to parse, with no deviations in style or structure.
With 7 tools, the count is reasonable for a server focused on interacting with a cursor-agent, covering analysis, chatting, editing, planning, raw execution, running, and searching. It's slightly lean but well-scoped, as each tool addresses a specific aspect of agent interaction without obvious bloat.
The tool surface covers key operations like analysis, chatting, editing, planning, and searching, but there are gaps in lifecycle coverage—for example, no tools for managing agent sessions, handling errors, or providing feedback on previous actions. The domain is prompt-based agent interaction, and while core workflows are present, the set lacks comprehensive support for advanced or iterative tasks.
Research-backed linting + generation for agent context files (CLAUDE.md, AGENTS.md, Cursor rules).
Cross-agent artifact workspace with provenance across Claude Code, Codex, Cursor, LangGraph.
Source-checked CLI guides and model-aware planning for Claude Code, Codex, and Grok Build.
Agent personas for Claude. 16 tools, 13 personas, 3 workflows. Zero extra API cost. Free.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/sailay1996/cursor-agent-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
