Cursor Integration Guide

Cursor is an AI-first code editor with built-in support for the Model Context Protocol (MCP). Once Proxima is registered as an MCP server, Cursor's Agent and Chat can call Proxima's 41 tools to search the web, query ChatGPT, Claude, Gemini or Perplexity, review code, or run multi-model checks. This guide uses the mcp.json file, which is the form Cursor documents for custom servers.

Before you start: install Proxima, open the desktop app, and log in to at least one provider (or add a BYOK key). The MCP entry point src/mcp/index.js forwards each call to the desktop app, so the app must be running when Cursor uses a tool. You also need Node.js 18 or newer on your PATH.

1. Add Proxima to mcp.json

Cursor reads MCP servers from mcp.json in two places. Pick the one that matches how you want to use Proxima:

ScopeFileUse it when
Global (all projects)~/.cursor/mcp.json
Windows: %USERPROFILE%\.cursor\mcp.json
You want Proxima in every workspace. This is the usual choice, because the path to Proxima does not depend on a project.
Project.cursor/mcp.json in the project rootYou want to share the setup with a team through git. Avoid committing absolute paths that only exist on your machine.

Create the file if it does not exist, and add the server under mcpServers. Replace the path with the real location of src/mcp/index.js in your Proxima folder (the Settings tab in the Proxima app can show you the exact block for your machine):

{ "mcpServers": { "proxima": { "command": "node", "args": [ "C:/path/to/proxima/src/mcp/index.js" ] } } }

On Windows, write the path with forward slashes (C:/Users/you/Proxima/src/mcp/index.js). A single backslash is an escape character in JSON and breaks the path. If you already have other servers in the file, add "proxima" next to them inside the same mcpServers object.

Sharing with a team: Cursor can expand ${userHome} and ${workspaceFolder} inside command and args, which lets a project-level file avoid hard-coded user names. Proxima itself is installed per machine, so keep its install folder in a global file or an environment-specific setting.

2. Check that Cursor sees it

1 Save the file. If Cursor does not pick the change up, reload the window or restart Cursor.
2 Open Cursor Settings and go to the MCP section (it appears as Tools & MCP or on the Customize page, depending on your Cursor version).
3 Find proxima. It should show as enabled with a tool count of 41. If it shows an error, open the logs from the same screen: the message usually names the missing file or the missing node command.
4 Open a chat in Agent mode and ask it to call list_available_models. A model list proves the whole chain works: Cursor to the MCP process to the Proxima app to your logged-in accounts.

3. Using Proxima inside Cursor

Cursor shows the tool list to its agent, which then decides when a tool helps. You can leave that to the agent, or name a tool yourself.

A. Automatic selection

Ask a question that needs outside information, for example how a library changed in its latest release. The agent can call deep_search or ddg_search, read a page with web_scrape, or analyze a folder with analyze_file before it answers. Cursor asks for your approval before running an MCP tool unless you have allowed it.

B. Naming a tool

"Use proxima ask_claude to review the token refresh logic in auth.js" "Call proxima smart_query in verify mode to check this migration plan" "Run proxima security_audit on this handler, then fix what it finds" "Use proxima ask_gemini with thinking_level high to check this algorithm's complexity"

C. Picking the right model

Model names depend on your accounts. Ask the agent to call list_available_models first, then use a name from its answer. Naming a model your account does not have returns an error that points back to this tool, rather than quietly using a different one.

4. Troubleshooting

  • Server shows an error or never turns on. Check the JSON for a trailing comma, use forward slashes in the path, and run node --version in a terminal (Node 18+). If node is not on the PATH that Cursor sees, put the full path to the node binary in command.
  • Server is on, but tool calls fail. Make sure the Proxima desktop app is running and a provider is logged in. ddg_search does not need a provider, so it is a good way to tell a bridge problem from an expired login.
  • Tools are missing after an upgrade. Proxima 5.5.0 registers 41 tools. Toggle the server off and on in Cursor so it reloads the tool list.

More cases are covered in the troubleshooting guide. Cursor's own reference for mcp.json is at cursor.com/docs/mcp.