How to use an MCP server in Cursor

To use an MCP server in Cursor: generate the server from your OpenAPI spec, then add it to .cursor/mcp.json (project, shared with your team) or ~/.cursor/mcp.json (global, personal) under a top-level mcpServers key. Cursor reads that file, connects to the server, and gives its agent every tool the server exposes. This post walks the two-step version — generate with Sourced, wire into Cursor — verified against Cursor's own docs.

Step 1: generate the MCP server from your spec

Cursor doesn't read an OpenAPI spec directly; it reads an MCP server. Sourced's OpenAPI-to-MCP workflow takes one spec and produces a reviewed tool surface, a safety report, default-enabled read-only tools, install snippets, and either a managed remote endpoint or a downloadable TypeScript server. Review the tool list before touching Cursor's config — reviewing the tool surface first is the point, not an afterthought.

For the shortest remote path, select Host with Sourced. Copy the hosted URL and one-time endpoint token into the remote entry below. The upstream API credential stays encrypted on the server and does not belong in Cursor's config.

Step 2: add it to Cursor's mcp.json

Cursor supports two config locations, per Cursor's docs:

• Project-specific, shared with your team via source control: .cursor/mcp.json in the project root.
• Global, personal to you across all projects: ~/.cursor/mcp.json in your home directory.

If a server name exists in both, the project-level config wins.

For a locally-built server (the common case right after generating), use a stdio entry:

{
  "mcpServers": {
    "your-api": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": {
        "YOUR_API_API_KEY": "your-key-here"
      }
    }
  }
}

If you've deployed the generated server behind HTTPS instead, use a remote entry:

{
  "mcpServers": {
    "your-api": {
      "url": "https://mcp.your-api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer your-token-here"
      }
    }
  }
}

Cursor also supports variable interpolation in command, args, env, url, and headers — ${env:NAME} for environment variables, ${workspaceFolder} for the project root, ${userHome} for your home directory — useful for keeping the committed .cursor/mcp.json free of literal paths and secrets. For a remote server with OAuth instead of a static header, Cursor's docs describe an auth block with CLIENT_ID, CLIENT_SECRET, and scopes; register Cursor's redirect URL with your OAuth provider before relying on it.

Once the file is saved, open Cursor's Customize panel to confirm the server shows as connected and toggle it on — you can disable a configured server without deleting its entry.

What Cursor's agent can then do

Once connected, Cursor's agent sees every tool your MCP server exposes — one per OpenAPI operation, by default, unless you generated with a narrower or task-shaped tool set — and can call them mid-conversation the same way it calls its built-in file and terminal tools. Ask it to "look up the customer by email and summarize their last three orders" and, if your spec has the matching read operations, it plans and calls them without you writing glue code. Write and destructive tools should still prompt for confirmation or stay out of the default set entirely; that's a property of how the server was generated, not of Cursor.

Review before you enable it

Before adding any generated server to .cursor/mcp.json — yours or a third party's — walk the checklist from the MCP security post: least-privilege credentials, destructive tools separated from read tools, argument validation, and no secrets committed in the JSON itself (use env interpolation instead). A project-level .cursor/mcp.json is shared with your whole team the moment it's committed — treat it like any other config file that ends up in git history.

Project vs global config

	.cursor/mcp.json (project)	~/.cursor/mcp.json (global)
Scope	This repo, shared via git	Every project on your machine
Good for	An API tied to this codebase, team-shared servers	Personal utilities you want everywhere
Precedence	Wins if names collide	Loses to project config on a name collision
Secrets	Use ${env:NAME} interpolation, not literals	Same — literals here still land on disk

Honest scope: when a plain API call beats MCP in Cursor

If you need Cursor's agent to hit an endpoint once or twice while you're debugging, a documented curl command in your README or a quick request from Cursor's own terminal is faster than generating, reviewing, and wiring an MCP server. MCP earns its setup cost when the agent needs the same tools repeatedly across sessions, when non-engineers on your team also need the tool surface without reading API docs, or when you want the identical server reused in Claude Code, Copilot, or another MCP host — see the OpenAPI-to-MCP server post for what translates cleanly from a spec and what still needs human review.

FAQ

Where does Cursor's MCP config file live?

Two places: .cursor/mcp.json in the project root for team-shared servers checked into git, or ~/.cursor/mcp.json in your home directory for servers you want available in every project. Project config takes precedence when a server name appears in both.

What are the required JSON keys for a local MCP server in Cursor?

A mcpServers object at the top level, then per server: command (the executable) and args (its arguments) are required for a local stdio server; env is optional for passing credentials.

What keys does a remote MCP server need in Cursor?

url is required; headers is optional for auth like a bearer token. Cursor also supports a static auth block with CLIENT_ID/CLIENT_SECRET/scopes for OAuth-based remote servers.

Can I generate a Cursor-ready MCP server from an existing OpenAPI spec?

Yes. Sourced's OpenAPI-to-MCP workflow produces a TypeScript MCP server or a managed remote endpoint plus install snippets for Cursor and several other hosts — you review the tool surface before wiring it in, rather than hand-writing tool definitions.

Is it safe to commit .cursor/mcp.json to my repo?

Only if it has no literal secrets in it. Use Cursor's ${env:NAME} interpolation for API keys and tokens so the committed file references environment variables instead of holding credentials directly.

Does Cursor support both local and remote MCP servers?

Yes — a command/args entry for a local process over stdio, or a url entry for a remote HTTP/SSE server. You can mix both in the same mcpServers object.

Ready to try it. Generate and host an MCP server from your OpenAPI spec, or compare the managed and self-hosted paths in the MCP server hosting guide.