Cursor-mcp

Cursor MCP Integration (Model Context Protocol) Overview: Cursor (an AI code editor) uses the Model Context Protocol (MCP) to integrate external tools and data sources into its AI assistant[1][2]. Alph CLI can leverage Cursor’s MCP support to connect local or remote services across macOS, Linux, and Windows. Cursor supports all three MCP transports – STDIO, Server-Sent Events (SSE), and Streamable HTTP – with unified protocols and JSON-RPC message exchange under the hood[3][4]. Platform Compatibility & Installation • Installation of Cursor: Cursor is available on macOS, Windows, and Linux (as an IDE extension or desktop app). Ensure Cursor is installed and updated on the target platform[5]. No separate MCP binary is needed – Cursor itself contains the MCP client logic. • MCP Server Discovery: Cursor discovers MCP servers from configuration files. On macOS/Linux, global config resides at ~/.cursor/mcp.json[6]. On Windows, use the user home directory (e.g. C:\Users<User>.cursor\mcp.json). Additionally, a project-specific config can be placed at /.cursor/mcp.json inside a project folder[7]. Cursor does not auto-scan the system for servers; it only loads those defined in these config files or added via its UI/extension API. • One-Click Installation: Cursor offers a one-click UI for certain official integrations. For example, developers can provide an “Add to Cursor” link on documentation sites which triggers Cursor to register the MCP server automatically[8][9]. This simplifies installation for users (especially OAuth-backed services). Alph CLI integration can mimic this by instructing users to use those links or by programmatically adding the same config entries. • Manual Config (mcp.json): The mcp.json is a JSON file listing servers by name. For example, to configure a local server via Node and an API key, you might include: { "mcpServers": { "example-tool": { "command": "npx", "args": ["-y", "example-mcp-server"], "env": { "API_KEY": "YOUR_API_KEY" } } } } [10]. Here command can be any executable (or script) and args its arguments. Ensure the command is available in the PATH (for Windows, if using batch files like npx.cmd, you may need to prefix with "cmd" and "/c" in the args to run correctly[11][12]). • Extension API: For enterprise or programmatic setup, Cursor exposes an API (vscode.cursor.mcp.registerServer) to register servers dynamically[13][14]. This API accepts the same fields as mcp.json. Alph CLI can use this via a VS Code extension context if automating Cursor integration in managed environments. It supports both STDIO and HTTP/SSE servers via a unified config interface[15][16]. MCP Transports and Protocols Cursor’s MCP client supports three transport modes[2]: • STDIO (Local Process): Cursor spawns a local process and communicates over its stdin/stdout streams[17]. This is used for local tools (single-user). Integration: Alph CLI can leverage this by launching any MCP-compliant executable as a subprocess. Ensure the process prints only JSON-RPC to stdout (no stray logging), or it will “corrupt the JSON-RPC messages and break your server”[18]. Log to stderr or files instead[19]. Cursor will manage the process lifecycle, sending an initialize request and keeping the process alive for subsequent calls. • SSE (Legacy HTTP with dual endpoints): Cursor can connect to an SSE endpoint (e.g. https://host/path/sse) for remote servers[20]. In SSE mode, Cursor performs an HTTP GET to the /sse endpoint and expects the server to send an initial endpoint event containing a POST URL (for JSON-RPC messages)[21][22]. After handshake, Cursor sends requests via that POST URL, and receives events on the SSE stream[22][23]. This legacy protocol involves two URLs but is still supported for compatibility. Integration: Ensure any SSE server provides the endpoint event and maintains the SSE stream open. Cursor will auto-reconnect if needed and handle session IDs embedded in the URL[24]. • Streamable HTTP (Unified endpoint): This is the newer MCP protocol where a single endpoint (often /mcp) handles both request and streaming response[25]. Cursor’s docs refer to this as “Streamable HTTP”[26]. The client opens a connection (usually an HTTP POST or upgrade to keep-alive) and the server streams JSON-RPC responses in chunks (content type text/event-stream or chunked application/json) over the same connection[27]. Many modern MCP servers use this unified /mcp path. Integration: Cursor will treat any configured HTTP URL (not explicitly marked as SSE) as a streamable HTTP endpoint. Practically, if the server returns an EventStream content type, Cursor will handle it as streaming; otherwise as a normal HTTP JSON response. Alph CLI should be prepared to read partial JSON objects from an HTTP response if implementing a similar client. (Note: Cursor’s mcp.json doesn’t distinguish SSE vs HTTP; it infers the protocol. Servers ending in /sse typically use SSE, whereas /mcp implies the unified protocol.) • Protocol Details: All transports use JSON-RPC 2.0 for message encoding. On connection, Cursor sends an initialize request with its supported protocol version and capabilities[4]. The server must reply with an initialize result confirming capabilities (e.g. what tools/resources it offers)[28][29]. Cursor then sends an initialized notification[30]. After this handshake, tool calls occur via methods like tools/execute, resources/read, etc., and the server’s responses are delivered back over the chosen transport. This handshake is handled internally by Cursor – from an integration perspective, ensure your MCP server adheres to the spec so that Cursor’s handshake succeeds. If Alph CLI is acting as an MCP client, it must implement the same handshake order (initialize → initialized) before invoking any tool requests[31][32]. Authentication & Authorization Cursor handles auth for MCP servers primarily through environment variables and external OAuth flows: • API Keys via Env: For local servers, embed secrets in the env field of mcp.json. For example, passing {"MY_API_TOKEN": "abcd1234"} will set that in the server’s environment[10]. This is safer than hardcoding keys. Cursor encourages using env vars for any credentials[33][34]. Alph CLI integrators should do the same (e.g. use process.env or a secure store to supply tokens to the MCP process). • OAuth (Remote Servers): Cursor supports OAuth 2.0 for cloud MCP services that require it[35][36]. In Cursor’s UI, if you add an OAuth-protected server (often via the one-click flow), Cursor will prompt the user to authenticate in a browser (logging into e.g. Google, Asana, etc.)[37][38]. After OAuth, tokens are stored and refreshed automatically[39][38]. Integration: Alph CLI can’t directly drive Cursor’s OAuth flow, but if instructing users, you can have them add the server via Cursor’s interface and complete the login. Once done, Cursor caches the token and will include it on future calls. Cursor’s config doesn’t explicitly store the token; it’s managed internally (likely in an OAuth token vault within Cursor). • Custom Headers: If an MCP server uses a static bearer token or custom header, Cursor’s extension API supports specifying headers for HTTP/SSE servers[16][40]. For example, an MCP server requiring an API key in header could be registered as: vscode.cursor.mcp.registerServer({ name: "secure-api", server: { url: "https://api.example.com/mcp", headers: { "X-API-Key": "VALUE" } } }); [16][40]. In mcp.json, the equivalent would be including a "headers" object under the server config. (The public docs don’t show a raw JSON example with headers, but this is supported via the API.) If needed, confirm by testing or reviewing Cursor’s source – this detail isn’t explicitly in the user docs, so verifying with the Cursor team or using the extension API is advisable for critical integrations. • Tool Permissions: By default, Cursor’s AI asks for user approval before using any MCP tool that can perform actions[41]. The chat UI will prompt the user to allow or deny each tool execution. For Alph CLI integration testing, be aware that initial usage may be blocked pending approval. Users can disable this prompt by enabling “auto-run” (Yolo mode) in Cursor’s settings[42], which trusts all tools similar to running terminal commands directly. Alternatively, they can pre-approve specific servers. Integration engineers should not assume a tool will run automatically – it may require user click unless auto-run is on or the server is marked as trusted. Usage and Runtime Behavior • MCP in Cursor Chat: Once configured, MCP tools appear in Cursor’s “Available Tools” list in the UI. The AI agent will automatically leverage them when relevant to the user’s query[43]. Users can also explicitly invoke a tool by name in conversation. Alph CLI can integrate with this by ensuring that the tool naming and descriptions (provided by the server’s tools/list response) are clear – Cursor will display these to the user. Tools can be toggled on/off in Cursor’s settings UI if they cause issues[44]. • Logging and Debugging: Cursor provides an Output panel for MCP logs[45]. Users or integrators can open “MCP Logs” in Cursor (via View → Output → MCP Logs) to see connection messages, errors, and tool outputs[45]. This is crucial for debugging integration issues (e.g. failed handshake or JSON errors). If Alph CLI is orchestrating Cursor, it should instruct users to check this log for troubleshooting. Common issues like authentication failure or server crashes will appear here. • Error Handling: If an MCP server crashes or times out, Cursor catches it gracefully: the chat will show an error message for that tool call, mark it as failed, and continue operating other tools normally[46]. Cursor isolates each MCP server, so one misbehaving server does not derail the entire assistant[46]. It’s up to the user or integrator to restart or fix the server. Cursor does not automatically retry failed tool calls (the user can re-ask the query after addressing the issue). Alph CLI should follow a similar principle: handle each MCP connection independently and fail softly if one dies. • Timeouts: By default, Cursor waits for responses up to a generous timeframe (the Cursor docs don’t state an exact number, but other clients use ~600s). If a request exceeds the timeout, Cursor will log a timeout error. There is no mention of automatic retries in Cursor’s docs, so presumably a timed-out call simply fails and returns an error to the user[46]. Integration engineers might consider implementing retries or prompting the user to retry, especially for transient network issues. If needed, the mcp.json does not expose a timeout setting (unlike Gemini CLI), so this might be hard-coded – contacting Cursor support or testing a long-running request can help determine the limit. • STDIO Process Behavior: When using local processes, note that Cursor keeps the subprocess running after initialization. It doesn’t spawn a new process on each tool invocation – this reduces latency after the first call. The server remains attached for the session, and will shut down when Cursor exits or if the user disables that server. If Alph CLI spawns similar processes, it should do the same to avoid re-handshaking repeatedly. Also, ensure proper shutdown: Cursor will send a termination (by closing stdin/stdout or killing the process) when needed[47]. If Alph CLI needs to detach from Cursor, make sure to clean up any orphaned MCP server processes it started. • Resource and Prompt Attachments: Cursor supports MCP resources and prompts as well. For example, an MCP server can expose a document or database as a resource that the user can reference with an @ symbol in Cursor[48][49]. Cursor will fetch and attach resource content automatically when referenced. Similarly, MCP prompts (pre-defined multi-step workflows) become available as slash-commands in Cursor’s chat UI (e.g. /mcp__servername__promptname)[50][51]. Alph CLI integrators should be aware that if a server defines resources or prompts, Cursor’s UI will reflect those, enhancing user capabilities beyond just tools. Ensure that resource URIs and prompt names are unique and appropriately formatted (Cursor uses protocol://path for resource identifiers and double-underscore naming for prompts). • Images and Binary Data: MCP servers can return images or other binary data by encoding it in base64 within the JSON response. Cursor recognizes responses of the form { type: "image", data: "", mimeType: "" } and will display images directly in the chat[52][53]. Integration-wise, if Alph CLI uses any visual outputs from servers, confirm the server sends them in Cursor’s expected format. The Cursor docs even link to an example server that generates images[54]. This is an advanced feature, but valuable (e.g., for diagram-generating tools). • Security Considerations: Emphasize to users that MCP servers run code with their credentials and can access project data. Cursor’s docs advise to only install trusted servers, review their code, and sandbox where possible[55]. For Alph CLI, if suggesting the use of community MCP servers, echo these warnings. In particular, encourage use of least-privilege API keys and running untrusted servers via STDIO (locally) rather than granting them broad remote access[56][57]. STDIO servers are easier to firewall (since they run under the user’s account and can be monitored). • Cross-Platform Paths: On Windows, pay attention to path formats in config. Use double backslashes or forward slashes in args as needed. For example, a directory argument in args might need to be "C:\Users\Name\Documents" in JSON. Cursor likely handles ~ expansion on Unix but not on Windows, so provide absolute paths. Testing on each OS or consulting Cursor’s forum (e.g., a Cursor forum post noted initialization errors on Windows if path/env are misconfigured[58]) can catch issues.