docs: pin mcp.json vs .mcp.json for dual Cursor + Claude Code plugins

README.md

@@ -82,7 +82,7 @@ plugins/
 │   │   └── plugin.json        # Per-plugin manifest
 │   ├── skills/                # Agent skills (SKILL.md with frontmatter)
 │   ├── rules/                 # Cursor rules (.mdc files)
-│   ├── mcp.json               # MCP server definitions
+│   ├── mcp.json               # MCP server definitions (Cursor default)
 │   ├── README.md
 │   ├── CHANGELOG.md
 │   └── LICENSE

create-plugin/skills/create-plugin-scaffold/SKILL.md

@@ -47,11 +47,14 @@ This path makes the plugin immediately available to Cursor without any install s
    - Skills: `skills/<skill-name>/SKILL.md` with `name`, `description`
    - Agents: `agents/*.md` with `name`, `description`
    - Commands: `commands/*.(md|txt)` with `name`, `description`
-6. If repository uses `.cursor-plugin/marketplace.json`, add plugin entry:
+6. If the component set includes `mcpServers`, create `mcp.json` at the plugin root with the server definitions.
+   - The plugins reference documents `mcp.json` as the default MCP config filename. Claude Code's default is `.mcp.json`.
+   - If the repo also ships a `.mcp.json` for Claude Code with different server config, pin `mcpServers` in `plugin.json` to the intended file (e.g. `"mcpServers": "./mcp.json"`) so the Marketplace clone uses the correct one.
+7. If repository uses `.cursor-plugin/marketplace.json`, add plugin entry:
    - `name`
    - `source`
    - optional metadata (`description`, `keywords`, `category`, `tags`)
-7. Ensure all manifest paths are relative, valid, and do not use absolute paths or parent traversal.
+8. Ensure all manifest paths are relative, valid, and do not use absolute paths or parent traversal.
 
 ## Guardrails
 

create-plugin/skills/review-plugin-submission/SKILL.md

@@ -21,7 +21,8 @@ A plugin is implemented and needs a final quality check before submission or rel
    - Agents in `agents/` markdown files
    - Commands in `commands/` markdown or text files
    - Hooks in `hooks/hooks.json`
-   - MCP config in `mcp.json` (or `mcpServers` override)
+   - MCP config in `mcp.json` (or `mcpServers` override in `plugin.json`)
+   - If `.mcp.json` also exists (common in dual Cursor + Claude Code repos), verify MCP filename handling (see below)
 3. Verify component metadata:
    - Skills include `name` and `description` frontmatter
    - Rules include valid frontmatter and clear guidance
@@ -33,6 +34,17 @@ A plugin is implemented and needs a final quality check before submission or rel
    - `README.md` states purpose, installation, and component coverage
    - optional logo path is valid and repository-hosted
 
+## MCP filename handling
+
+The plugins reference documents `mcp.json` at the plugin root as the default MCP config filename. Claude Code's default is `.mcp.json`.
+
+When both `mcp.json` and `.mcp.json` exist at the plugin root with different contents, a Marketplace clone can start the unintended server. To control which file is used, set `mcpServers` in `plugin.json` to an explicit path (e.g. `"mcpServers": "./mcp.json"`).
+
+**Dual Cursor + Claude Code repos.** Shipping both filenames is the natural layout when one repository is published as a plugin for both clients. If the two files contain different server configs (e.g. hosted HTTP for Cursor, local stdio for Claude Code), the Marketplace clone may load the wrong one. Authors should either:
+
+- Keep a single shared file and point both clients at it, or
+- Pin `mcpServers` in `.cursor-plugin/plugin.json` to the intended file.
+
 ## Checklist
 
 - Manifest exists and parses as valid JSON
@@ -41,6 +53,7 @@ A plugin is implemented and needs a final quality check before submission or rel
 - No missing frontmatter on skills/rules/agents/commands
 - Plugin scope is clear and focused
 - Marketplace registration complete (if multi-plugin repo)
+- If both `mcp.json` and `.mcp.json` exist, either the payloads are identical or `mcpServers` is pinned in `plugin.json`
 
 ## Output