How to set up MCP servers in Cursor

Docs last checked: · We make Pith, the hosted MCP server used as the worked example. Every client step is checked against the vendor's own documentation, linked below.

The short answer

Cursor reads MCP servers from mcp.json: .cursor/mcp.json in a project, or ~/.cursor/mcp.json for all projects. A local server is a command with args (stdio); a remote server is a url, optionally with headers (Streamable HTTP or SSE). For remote servers Cursor runs OAuth itself — PKCE, dynamic client registration, automatic token refresh — or you pass a token via ${env:NAME}. Servers show up on the Customize page, where you switch them on and off; Cursor asks for approval before running an MCP tool by default. For Pith: "url": "https://mcp.pithlab.app/mcp".

Cursor's agent already reads your code. An MCP server lets it reach everything else: a database, an issue tracker, a browser — or the articles, papers and standards you read while working on the code. MCP, the Model Context Protocol, is the same open standard Claude and ChatGPT use, so a server you set up once works across all three.

This guide follows Cursor's own documentation as of 8 November 2026: where the config lives, local versus remote servers, sign-in with OAuth or a token, approvals and rules, and how to debug. It ends with a worked example that matters for anyone who writes as much as they code — docs, specs, blog posts, research notes: connecting a knowledge server, Pith's hosted MCP, so Cursor can cite your saved sources while you write.

Where Cursor's MCP config lives: project vs global mcp.json

Cursor has two config files with the same format:

  • Project: .cursor/mcp.json in the project root — tools for this repository. Commit it if the whole team should get the same servers (without secrets in it).
  • Global: ~/.cursor/mcp.json in your home folder — tools available in every project. The right place for personal servers such as your own knowledge base.

You can also install servers with one click from the Cursor Marketplace on the Customize page, or browse community servers on cursor.directory. Installed and configured servers appear on the Customize page, where you enable or disable them without deleting the config.

Local (stdio) or remote (URL) server?

Cursor supports three transports: stdio (a local command, single user), SSE and Streamable HTTP (a URL, local or remote, many users). In mcp.json the difference is simply command versus url:

~/.cursor/mcp.json — a local stdio server
{
  "mcpServers": {
    "my-local-server": {
      "command": "npx",
      "args": ["-y", "some-mcp-server"],
      "env": { "API_KEY": "${env:SOME_API_KEY}" }
    }
  }
}
~/.cursor/mcp.json — a remote server
{
  "mcpServers": {
    "pith": {
      "url": "https://mcp.pithlab.app/mcp"
    }
  }
}

Choose local when the server needs your machine — files on disk, a local database, a CLI only you have — or when, as Cursor's security notes put it, you want sensitive data to stay on a server you run yourself. Choose remote when the data already lives in a hosted service: nothing to install or update, and the same server works from Claude and ChatGPT too.

Config values can use variables instead of literals: ${env:NAME} for environment variables, ${userHome}, ${workspaceFolder}, ${workspaceFolderBasename} and ${pathSeparator} (or ${/}). Cursor's advice: never hard-code secrets, use environment variables.

Signing in: OAuth or a token

OAuth (automatic). For a remote server that supports it, Cursor reads the server's protected-resource metadata and runs “the authorization code flow with PKCE”; with dynamic client registration it “registers as a public client with no client secret”, and it renews an expired access token with the refresh token. You only confirm on the service's consent page.

Static OAuth client. If a server does not support dynamic registration, you add auth with CLIENT_ID, CLIENT_SECRET and scopes to the server's entry. The redirect URLs to register with the provider are http://localhost:8787/callback for the desktop app and https://www.cursor.com/agents/mcp/oauth/callback for web and agents.

Token in a header. Many servers simply accept an API token. Put it in headers and read it from the environment, so the config file can be shared:

~/.cursor/mcp.json — remote server with a token from the environment
{
  "mcpServers": {
    "pith": {
      "url": "https://mcp.pithlab.app/mcp",
      "headers": { "Authorization": "Bearer ${env:PITH_TOKEN}" }
    }
  }
}

Cloud Agents keep their own MCP sign-ins on Cursor's servers, separate from the sign-ins on your machine — expect to authorise a server once more there.

Using MCP tools in Cursor: approvals, prompts and rules

Once a server is connected, Cursor's agent uses its tools automatically when they are relevant; you can also name the server or tool in your request. Cursor asks for approval before using MCP tools by default, and MCP follows the same run modes as terminal commands, so switch on auto-run only for servers whose tools you trust.

Cursor supports more of MCP than tools: prompts, resources, roots, elicitation and MCP Apps (interactive views). A server's prompts are ready-made workflows — Pith ships fact_check (check a draft against your own sources), client_prep, capture and maintain_wiki.

To make the agent reach for a server without being asked, add a project rule. Rules live in .cursor/rules as .mdc files with frontmatter; “Apply Intelligently” lets the agent decide from the description, “Always Apply” includes it in every chat. An AGENTS.md in the project root works as a simpler alternative.

.cursor/rules/sources.mdc — tell the agent to cite your saved sources
---
description: "Use when writing docs, specs, changelogs or posts that make factual claims"
alwaysApply: false
---

- Before stating a fact about a standard, regulation, library or market,
  search my saved sources with the Pith MCP tools (search_everything).
- Cite the source URL for every such claim. If Pith has nothing, say so
  instead of guessing.

Worked example: a knowledge MCP while you write and code

Pith is a hosted reading memory: you save articles, PDFs, papers and newsletters; it builds a cited wiki, a morning report and meaning-based search across everything you saved. In Cursor that turns into “answer from what I actually read” — useful for READMEs, architecture notes, RFCs and blog posts. We make Pith; the setup is the same for any remote server.

  1. 1

    Save your sources in Pith

    Save the docs pages, papers and articles you rely on — with the Chrome extension (including the page text you're reading), the iPhone Shortcut or Android share sheet, or by importing from Pocket, Raindrop, Instapaper or Readwise. PDF links are read with text recognition. Saving, reading and searching are free.

  2. 2

    Create an MCP token

    In Pith, open Settings → API tokens → “Generate MCP token”, pick the workspace and the scopes (read-only is enough for citing), and copy the tfk_… token — it is shown once.

  3. 3

    Add Pith to your global mcp.json

    Put the entry with "url": "https://mcp.pithlab.app/mcp" and the Authorization: Bearer ${env:PITH_TOKEN} header into ~/.cursor/mcp.json, and set PITH_TOKEN in your shell profile. (Alternatively, leave out the header and let Cursor's OAuth sign-in run — Pith supports dynamic client registration.)

  4. 4

    Check it on the Customize page

    Restart Cursor if needed, open Customize and make sure the Pith server is enabled and lists its tools.

  5. 5

    Ask while you write

    In the agent chat: “Draft the ‘Compliance’ section of this README from my saved sources on the EU Cyber Resilience Act — cite each claim.” The agent calls search_everything, reads key facts with get_bookmark_facts, checks exact wording with get_bookmark_content, and writes the section with source links.

More tools that help in an editor: search_wiki_pages and get_wiki_page (your cited wiki pages, including source conflicts), list_highlights (passages you marked), list_deadlines (dates from your sources, e.g. when a regulation applies) and write_note (park a finding as a Pith note). With a write scope, save_bookmark saves a docs page the agent just found. Reads and wiki writes over MCP are free.

Interactive views: Cursor supports MCP Apps, and Pith serves them on https://mcp.pithlab.app/apps — add it as a second server entry. check_citations checks the claims of a draft against your saved sources only (49 ct per started 10 pages from Pith's prepaid credit).

Where data sits: Pith is hosted in Germany; its AI processing (summaries and the embeddings behind meaning-based search) runs through OpenAI in the US. What the agent reads from Pith then goes to the model you use in Cursor.

Troubleshooting and security

Logs: open the Output panel (Cmd+Shift+U on macOS), choose “MCP Logs” from the dropdown and look for connection errors, authentication problems or server crashes. For a local server, run its command in a terminal once — the real error is usually printed there. For a remote server, check that the URL includes the path (often /mcp).

Security checklist, following Cursor's own guidance:

  • Verify where a server comes from and what it can do before you add it; read the source of local servers that touch sensitive systems.
  • Use API keys with the smallest scopes that work — for citing, a Pith token with read scopes only.
  • Keep secrets in environment variables, not in a committed .cursor/mcp.json.
  • Keep approvals on for servers with write tools; remember the server sees each tool call's arguments (the query, the text to save), not your whole chat.
  • Revoke tokens you no longer use — in Pith under Settings → API tokens.

Frequently asked questions

Where is Cursor's MCP config file?

.cursor/mcp.json in the project root for project-specific servers, ~/.cursor/mcp.json in your home folder for servers available in every project. Both use the same mcpServers format.

Does Cursor support remote MCP servers with OAuth?

Yes. Cursor runs the OAuth authorization-code flow with PKCE, registers itself via dynamic client registration where the server supports it, and refreshes tokens automatically. For servers without dynamic registration you can add a static client ID and secret under auth.

How do I pass an API key to an MCP server in Cursor without committing it?

Reference an environment variable in mcp.json, for example "Authorization": "Bearer ${env:PITH_TOKEN}" in headers or "API_KEY": "${env:API_KEY}" in env, and set the variable in your shell.

Why doesn't Cursor's agent use my MCP server?

Check that the server is enabled on the Customize page and lists its tools, look at the MCP Logs in the Output panel, and name the server in your request. A project rule in .cursor/rules makes the agent reach for it on its own.

Can I use the same MCP server in Cursor, Claude and ChatGPT?

Yes, if it is a remote server — that is the point of the standard. Pith's server at https://mcp.pithlab.app/mcp works in all three; see the Claude and ChatGPT guides.

What does Pith cost in Cursor?

Connecting is free, and reads and wiki writes over MCP are free. Saving, reading and searching are free; AI actions such as the citation check are paid per use from a prepaid credit, with €1 free credit every month — see pricing.

More guides

Sources (vendor docs we checked)

Give your assistant a memory of what you read.

Save free, connect over MCP, and let Claude, ChatGPT or Cursor answer from your sources — with citations.

Docs last checked: 8 November 2026 · Licensed CC BY 4.0 · cite freely with attribution to Pith.