Cursor Agent MCP Server

Instructions

Implementation Reference

• server.js:276-297 (registration)

  Registration of the 'cursor_agent_chat' MCP tool, including name, description, Zod input schema, and inline handler function that normalizes args and calls runCursorAgent.

  server.tool(
    'cursor_agent_chat',
    'Chat with cursor-agent using a prompt and optional model/force/output_format.',
    CHAT_SCHEMA.shape,
    async (args) => {
      try {
        // Normalize prompt in case the host nests under "arguments"
        const prompt =
          (args && typeof args === 'object' && 'prompt' in args ? args.prompt : undefined) ??
          (args && typeof args === 'object' && args.arguments && typeof args.arguments === 'object' ? args.arguments.prompt : undefined);
  
        const flat = {
          ...(args && typeof args === 'object' && args.arguments && typeof args.arguments === 'object' ? args.arguments : args),
          prompt,
        };
  
        return await runCursorAgent(flat);
      } catch (e) {
        return { content: [{ type: 'text', text: `Invalid params: ${e?.message || e}` }], isError: true };
      }
    },
  );

• server.js:280-296 (handler)

  Inline handler function for cursor_agent_chat tool. Normalizes input arguments to handle both flat and nested 'arguments' structures from different MCP hosts, then delegates execution to the shared runCursorAgent helper.

  async (args) => {
    try {
      // Normalize prompt in case the host nests under "arguments"
      const prompt =
        (args && typeof args === 'object' && 'prompt' in args ? args.prompt : undefined) ??
        (args && typeof args === 'object' && args.arguments && typeof args.arguments === 'object' ? args.arguments.prompt : undefined);
  
      const flat = {
        ...(args && typeof args === 'object' && args.arguments && typeof args.arguments === 'object' ? args.arguments : args),
        prompt,
      };
  
      return await runCursorAgent(flat);
    } catch (e) {
      return { content: [{ type: 'text', text: `Invalid params: ${e?.message || e}` }], isError: true };
    }
  },

• server.js:222-237 (schema)

  Zod schema definitions for cursor_agent_chat: CHAT_SCHEMA requires 'prompt' string and spreads shared COMMON fields for optional CLI options like output_format, model, force, etc.

  const COMMON = {
   output_format: z.enum(['text', 'json', 'markdown']).default('text'),
   extra_args: z.array(z.string()).optional(),
   cwd: z.string().optional(),
   executable: z.string().optional(),
   model: z.string().optional(),
   force: z.boolean().optional(),
   // When true, the server will prepend the effective prompt to the tool output (useful for Claude debugging)
   echo_prompt: z.boolean().optional(),
  };
  
  // Schemas
  const CHAT_SCHEMA = z.object({
   prompt: z.string().min(1, 'prompt is required'),
   ...COMMON,
  });

• server.js:153-193 (helper)

  Shared helper invoked by cursor_agent_chat (and other tools) to construct argv from prompt and extra_args, invoke the cursor-agent CLI executable, handle output formatting, debug logging, and optional prompt echoing.

  async function runCursorAgent(input) {
    const source = (input && typeof input === 'object' && input.arguments && typeof input.prompt === 'undefined')
      ? input.arguments
      : input;
  
    const {
      prompt,
      output_format = 'text',
      extra_args,
      cwd,
      executable,
      model,
      force,
    } = source || {};
  
    const argv = [...(extra_args ?? []), String(prompt)];
    const usedPrompt = argv.length ? String(argv[argv.length - 1]) : '';
   
    // Optional prompt echo and debug diagnostics
    if (process.env.DEBUG_CURSOR_MCP === '1') {
      try {
        const preview = usedPrompt.slice(0, 400).replace(/\n/g, '\\n');
        console.error('[cursor-mcp] prompt:', preview);
        if (extra_args?.length) console.error('[cursor-mcp] extra_args:', JSON.stringify(extra_args));
        if (model) console.error('[cursor-mcp] model:', model);
        if (typeof force === 'boolean') console.error('[cursor-mcp] force:', String(force));
      } catch {}
    }
   
    const result = await invokeCursorAgent({ argv, output_format, cwd, executable, model, force });
   
    // Echo prompt either when env is set or when caller provided echo_prompt: true (if host forwards unknown args it's fine)
    const echoEnabled = process.env.CURSOR_AGENT_ECHO_PROMPT === '1' || source?.echo_prompt === true;
    if (echoEnabled) {
      const text = `Prompt used:\n${usedPrompt}`;
      const content = Array.isArray(result?.content) ? result.content : [];
      return { ...result, content: [{ type: 'text', text }, ...content] };
    }
   
    return result;
  }