Cursor MCP Setup With a Single Endpoint

Start With One Cursor Server Entry

Cursor can load MCP servers from a project file at .cursor/mcp.json or a user file at ~/.cursor/mcp.json. For a team repository, the project file is the right place for a shared endpoint name and URL. It should not contain a teammate's API key, a database password, or a bundle of per-source secrets. Keep the committed file as the wiring contract: Cursor talks to one workspace server, and each developer supplies their own credential outside the repository.

A minimal remote entry looks like this:

{
  "mcpServers": {
    "workspace": {
      "url": "https://mcp.example.com/agent/mcp",
      "headers": {
        "Authorization": "Bearer ${env:WORKSPACE_MCP_KEY}"
      }
    }
  }
}

Cursor resolves variables in url and headers, including ${env:NAME}, so the endpoint can be reviewed in git while the key comes from the user's environment. Remote servers use a URL and headers rather than a local command; Cursor also supports OAuth for servers that require it. Name the server after the integration boundary, not after one upstream such as GitHub or Postgres.

Why Not Put Every Source in Cursor

Cursor's MCP file is a client configuration file. It is not a durable integration registry, permission system, credential vault or audit log. If a repository lists ten unrelated MCP servers, every developer has to reason about ten names, ten authentication paths, ten failure modes and ten update cadences before the agent even starts using tools. The file also becomes harder to share because one server may be safe for every teammate while another needs production-only access.

A single endpoint changes the failure surface. Cursor still sees an MCP server, but that server can organize upstream systems behind a stable boundary. The boundary can keep source names consistent, prevent tool-name collisions, enforce read and write grants, and report when a source exists but is withheld for the caller. It can also keep the tool list small. For the broader design pattern, compare the MCP gateway guide and context bloat from too many MCP tools.

This is especially useful in code work. A Cursor prompt often starts inside one repository, but the answer may require an issue tracker, a deployment log, a billing API, an internal REST endpoint and a database view. Those systems should not be copied into every repo's Cursor file. Cursor should know how to reach the workspace integration layer; the layer should know which systems belong to the workspace and which tools the current credential may call.

Use the Protocol Boundary Directly

MCP over Streamable HTTP sends each client message as an HTTP POST to a single MCP endpoint, and MCP messages are JSON-RPC. That makes a single remote endpoint a natural fit for Cursor: one URL carries discovery, calls, authorization metadata and errors. Do not validate the setup only by asking Cursor a broad natural-language question. Validate the protocol surface you expect the agent to use.

The first check is tool discovery. For the same key, the answer should be deterministic enough to review, and small enough that Cursor is not deciding among every company tool at once:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

The second check is a harmless read call with concrete arguments. MCP invokes tools with tools/call; the tool name and argument object are the contract the model will use:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "workspace.search_issues",
    "arguments": {
      "query": "checkout timeout",
      "limit": 5
    }
  }
}

Record the expected source, tool, argument schema, permission decision and output shape before rolling the entry out. If Cursor shows the tool call in chat with expandable arguments, a reviewer should be able to connect that visible action back to the same source and audit record. The protocol allows the tool set to vary by authorization, so the same endpoint can legitimately return different tools for a read-only key and a release key.

Roll It Out Without Leaking Secrets

1. Choose whether the endpoint belongs in .cursor/mcp.json for the repository or ~/.cursor/mcp.json for one user. Use the project file only for configuration the team can safely review.
2. Name the server after the shared boundary, such as workspace, company or spyn3. Avoid names that imply one upstream system when the endpoint fronts several.
3. Put the URL in the file and interpolate the authorization header from ${env:...}. Do not use a committed fallback token.
4. Have one developer start with a read-only credential and confirm that Cursor loads the server from Customize or the available tools list.
5. Ask Cursor to list sources or available toolsets before doing work. If the endpoint exposes everything immediately, stop and fix the boundary before adding more systems.
6. Run one successful read call, one denied write call and one denied source call. Keep all three results in the rollout note.
7. Repeat with another developer's key. The endpoint URL should stay the same while the visible sources and grants reflect that person's credential.

Do not treat a green setup check as production readiness. Test the path you will need during an incident: a missing environment variable, an expired OAuth grant, a source that is reachable but forbidden, and an upstream that is down. Cursor's own failure display is useful, but the integration layer still needs logs with actor, source, tool, decision, duration and result class. For key design, see scoped API keys for AI agents and tool-call audit logging.

Handle OAuth and Approvals Deliberately

Header-based API keys are simple for a first Cursor rollout, but many remote MCP servers use OAuth. Cursor can configure remote servers with an auth object when a provider requires static client credentials, and the MCP authorization specification defines the HTTP authorization flow for restricted servers. Whether the credential is a key or an OAuth grant, request the smallest useful scope and keep source policy outside the prompt.

Cursor asks for approval before MCP tool use by default and shows tool arguments in the approval surface. That is helpful, but it is not the whole permission model. A model can choose a risky tool; a human can approve it; a prompt can be ambiguous. The server still has to reject calls that the presented credential cannot make. If the first rollout only needs read-only investigation, issue a key or grant that cannot call write tools.

Make approval behavior part of acceptance testing. A good test prompt is specific: "Find the five most recent open checkout timeout issues, summarize titles and links, and do not modify anything." The expected path is source discovery, an issue-search read tool, a compact answer and no write approval. Then ask for an edit that the key should not be allowed to perform. The useful result is a clear denial, not a hidden missing tool.

Using Cursor with SPYN3

In Cursor, SPYN3 is a single entry in .cursor/mcp.json: an mcpServers.spyn3 object with the url https://api.spyn3.com/agent/mcp and an Authorization header carrying the key. The same block works in other clients, which is the point. Whether a client refreshes its tool list after enable_toolset varies between clients, so SPYN3 does not depend on it: the agent can always call an opened source's tools through call_tool.

Review Checklist

After the first repository works, resist copying the file blindly everywhere. Some repos need the shared project entry; others only need a personal global entry. What should stay constant is the boundary: Cursor gets one MCP server for the workspace, while upstream credentials, source expansion, write grants, audit logs and rotations live behind it.