Cursor @Docs vs MCP: what to use now
Cursor @Docs vs MCP explained: choose lightweight docs, project rules, an existing docs MCP or a custom MCP without overbuilding.
Faisal Karkoh · 25 Oct 2026 · 9 min read
If Cursor is using the wrong framework or library documentation, the fix is not automatically MCP. The outcome you want is simpler: Cursor should know which documentation source and version to rely on, make the smallest safe code change, and leave you with something you can verify. If the broader decision is whether Cursor belongs in your everyday coding workflow at all, start with the separate Cursor vs ChatGPT for daily coding work comparison before designing documentation infrastructure.
Evidence note: this article is based on Cursor documentation, release notes and Cursor Marketplace pages accessed on 2026-10-25. It is researched guidance, not a field test of Cursor, Context7 or a private MCP server.
The short answer: @Docs is not the current decision point
The old question, Cursor @Docs vs MCP, starts from the wrong place. Cursor’s current IDE release notes say the Docs category and Add New Custom Docs option were removed from the @ menu because they had already stopped adding documentation to agent context. The same note says Docs chips may still appear in older conversations, which explains why older screenshots and advice can still cause confusion. See Cursor’s IDE release notes for the current wording.
Cursor’s current Agent prompting docs list the active @ mention categories, which is the relevant reference point for the article’s @Docs discussion.
Cursor’s current Agent prompting documentation lists @ mentions for files and folders, terminal output, previous chats, git diffs and the built-in browser. It does not list @Docs as a current Agent context path. Cursor’s Agent prompting documentation is the better reference point than older @Docs-era posts.
So the practical decision is not whether MCP has replaced @Docs. The useful question is: how much documentation infrastructure does this task justify?
- For one known public page, attach or provide the source directly.
- For a short stable reference, keep a local Markdown file in the repository.
- For repeatable project guidance, use a focused Cursor rule that points to canonical files.
- For repeated public version-specific documentation lookup, consider an existing documentation MCP such as Context7.
- For private, authenticated, dynamic or governed knowledge, consider a reviewed custom MCP setup.
The five practical ways to give Cursor documentation
1. Provide the source directly
If the task depends on one or two known pages, the lightest workflow is to give Cursor the exact source before it edits code. That might be a copied excerpt, a browser context source where appropriate, or a short instruction that identifies the documentation page and version.
The Context7 marketplace listing shows the kind of existing documentation MCP the article refers to, without turning the workflow into a custom MCP build.
This is the right default when the problem is narrow: one API route pattern, one SDK method, one migration syntax or one component convention. MCP adds little value if the answer is on a single page and the real work is checking that Cursor followed it.
2. Keep a local Markdown docs snapshot
A local file works well when the source is short, stable and important enough to live with the repository. Examples include an internal migration convention, an SDK integration note, or a pinned summary of a framework pattern for this project.
Label the file clearly, include the upstream version or date, and keep it small. Treat it as a reference file, not as a place to dump an entire documentation site.
3. Add a focused Cursor project rule
Cursor rules are better for repeatable project knowledge than for large pasted documentation. Cursor’s Rules documentation says project rules can encode domain-specific knowledge and workflows, and advises keeping rules focused. It also says to reference files instead of copying large bodies of content into rules. For a deeper rule-writing pattern, see Cursor rules for a real project.
That distinction matters. A rule can say: when changing database migrations, read @docs/migration-standard.md first and follow its version assumptions. Cursor states that a file mention in a rule tells Agent where to look; the file contents are not automatically inlined into the prompt.
4. Use an existing documentation MCP when lookup repeats
MCP is Cursor’s mechanism for connecting to external tools and data sources, according to Cursor’s MCP documentation. It is not just a renamed version of @Docs.
An existing documentation MCP can make sense when Cursor repeatedly needs to query public documentation, especially where version-specific examples matter. Cursor Marketplace lists Context7 as a verified Cursor MCP server by Upstash for up-to-date, version-specific documentation and code examples from source repositories. That does not mean every team should install it; it means there is a lighter option than building a custom server when the public docs source is covered.
5. Build a custom MCP server only for a real integration problem
A custom MCP server is justified when the documentation problem has become an integration problem. That usually means private docs, authenticated systems, dynamic retrieval, several internal sources, shared team access patterns, audit requirements or tool actions.
Cursor MCP supports stdio, SSE and Streamable HTTP transports, and supports tools, prompts, resources, roots, elicitation and MCP Apps. That is powerful, but it also means more configuration, permissions and maintenance than a Markdown file or project rule.
Decision table: lightweight docs workflow, existing MCP or custom MCP
| Option | Best fit | Setup and maintenance | Freshness and version control | Main failure mode |
|---|
| Direct source or browser context | One known public page or a narrow API question | Lowest. Provide the source for the task. | Fresh if the source is current, but not automatically reusable. | Cursor edits without naming the exact page or version it used. |
| Local Markdown docs file | Small internal reference or pinned public-docs snapshot | Low. Keep the file short and update it deliberately. | Strong if the file is version-labelled and reviewed with the repo. | The snapshot becomes stale or too large to be useful. |
| Cursor project rule plus canonical file | Repeatable project convention or workflow | Low to medium. Maintain a focused rule and referenced file. | Good when the referenced file is version controlled. | The rule becomes a prompt dump instead of a pointer to a source. |
| Existing documentation MCP | Repeated public version-specific docs lookup | Medium. Install, review and manage the server. | Potentially better for changing public docs, depending on the server and source coverage. | Tool clutter, irrelevant retrieval or unclear source/version attribution. |
| Custom MCP server | Private, authenticated, dynamic, multi-source or auditable docs | Highest. Build, host, secure and maintain it. | Best when backed by governed internal systems. | Overbuilding a tool layer for a problem that a file or rule would solve. |
There is also a context cost. Cursor’s Agent prompting documentation says the context usage view counts MCP instructions and the catalog from connected MCP servers as chat context, alongside tools, rules, skills and conversation content. MCP is not free context, so connected servers should earn their place. The same principle applies to large repositories: keep context layered and explicit, as explained in designing coding agent context in large repos.
Worked example: implementing against current framework docs
Consider this illustrative scenario, not an observed test result. A developer is working in Cursor on a feature branch. The task is to add a feature using current public framework or library documentation. The developer knows the framework and the feature area, but not the exact page or version Cursor should rely on.
The smallest reliable workflow is a ladder, not a jump straight to MCP.
- Ask Cursor to identify the documentation it needs before editing. The prompt should ask for the exact docs source and version it plans to use, plus any uncertainty. If Cursor cannot state that, do not let it make risky API changes yet.
- If the task depends on one or two pages, provide those pages directly. This is enough for a single route handler, component pattern, SDK method or migration syntax. The expected output is code that matches the supplied source, not a broad documentation search.
- If the same reference will be reused, create a short repository file. For example, an illustrative file such as
docs/framework-api-pattern.md can contain the pinned version, the canonical link, the allowed pattern and one project-specific example. This is illustrative data, not a measured result. - If the convention should apply across the project, add a focused Cursor rule. The rule should point Cursor to the canonical file and say when to read it. It should not paste a large documentation body into the rule.
- If repeated public docs lookup is the real need, consider an existing docs MCP. This is where a verified marketplace listing such as Context7 may be relevant, assuming the docs source is covered and the team is comfortable with the permissions.
- Only consider a custom MCP server for private or governed retrieval. If the docs are behind authentication, spread across systems, dynamic, or require auditable team access, MCP may be the right architecture.
The expected result is not that Cursor always uses a sophisticated tool. The expected result is that Cursor can state which documentation source and version it used, the selected method is no heavier than the task requires, and the generated code can be checked against project commands such as typecheck, tests and build.
Stop the workflow if Cursor cannot name the docs source, uses deprecated APIs that do not match the supplied source, adds MCP tool clutter without improving retrieval, or proposes a custom MCP server for a single public page.
When MCP is justified, and when it is overbuilding
MCP is justified when Cursor needs a callable lookup or action layer, not just a memory aid. Use it when the agent needs to query a docs index repeatedly, retrieve authenticated internal references, combine several sources, or expose tool actions in a controlled way.
Cursor’s MCP documentation shows why MCP is a tool and data-source integration layer, not just a replacement for a pasted documentation page.
It is also reasonable when a team wants the same access pattern across repositories or cloud-agent workflows. Cursor supports project configuration in .cursor/mcp.json and global configuration in ~/.cursor/mcp.json. Project configuration is the relevant path when a docs tool should travel with a repository.
A custom MCP server is overbuilding when the problem is one public page, one short internal standard, or weak prompting. If Cursor is not being asked to identify its source and version before editing, adding a server will not fix the underlying verification gap.
A useful rule of thumb is this: use rules to tell Cursor when and where to look; use MCP when Cursor needs a tool to look something up, retrieve something dynamic, or perform an action.
Security, context and verification checks before accepting code
MCP changes the security boundary. Cursor’s MCP documentation says Cursor asks for approval before using MCP tools by default and can automatically use MCP tools listed under Available Tools when relevant, including in Plan Mode. It also warns that MCP servers can access external services and execute code on the user’s behalf. Cursor’s guidance is to install trusted servers, review permissions, limit API keys and audit critical integrations. If you are designing MCP beyond an editor-only setup, the security model in secure MCP apps on Vercel with Supabase is a useful companion pattern.
Do not treat .cursorignore as a complete MCP boundary. Cursor’s Ignore file documentation says .cursorignore can block code from Agent, Tab and @ mention references, but terminal and MCP server tools used by Agent cannot block access to code governed by .cursorignore. If a repository contains sensitive files, review MCP and terminal access separately.
Before accepting code generated with any documentation source, use this checklist:
- Ask Cursor to state the exact docs source and version before making risky edits.
- For a local docs snapshot, confirm the file is short, pinned and version labelled.
- For a rule, confirm it points to a canonical file instead of copying a large documentation body.
- For MCP, confirm the server is trusted, permissions are reviewed, credentials are narrow and unused servers are disabled.
- Run the project’s normal verification commands, such as typecheck, tests and build.
- Reject or revise the output if the code uses APIs that do not match the supplied or pinned documentation.
The practical answer to Cursor @Docs vs MCP is to start smaller than MCP unless the task proves it needs retrieval, authentication, sharing, auditability or tool actions. For the next feature, ask Cursor for the exact documentation source first; only add infrastructure when that source cannot be made reliable with a direct attachment, local file or focused rule.