[BUG] cursor: .cursor/mcp.json emitted with Copilot schema (type: "local") — stdio MCP servers fail to start in Cursor

[denifilatoff]

Describe the bug

When a package is installed with --client cursor, APM generates .cursor/mcp.json using the GitHub Copilot CLI server shape instead of Cursor's. The output contains "type": "local" plus Copilot-only fields ("tools", "id"). Cursor's MCP loader does not recognise "type": "local" for stdio servers, and the server silently fails to register. Manually changing "type": "local" → "type": "stdio" (and removing the Copilot fields) fixes the server.

Per Cursor docs — Model Context Protocol, stdio entries in .cursor/mcp.json must use "type": "stdio", together with command, and optionally args / env.

Root cause. CursorClientAdapter inherits from CopilotClientAdapter and reuses _format_server_config, which hard-codes the Copilot shape:

config = {
    "type": "local",
    "tools": ["*"],
    "id": server_info.get("id", ""),
}

For self-defined stdio deps (_raw_stdio) the adapter only appends command / args / env on top of this Copilot skeleton, so the resulting file is never valid for Cursor.

To Reproduce

Steps to reproduce the behavior:

1. Use any package that declares a self-defined stdio MCP server — e.g. vlsi/troubleshooting-cli → ai-packages/troubleshooting/apm.yml.
2. Install it targeting Cursor: apm install ... --client cursor.
3. Open the generated .cursor/mcp.json — it contains "type": "local".
4. Open the project in Cursor → the MCP server does not appear / fails to register.
5. Manually replace "type": "local" with "type": "stdio" → the server works immediately.

Expected behavior

.cursor/mcp.json should follow Cursor's documented stdio schema, e.g.:

{
  "mcpServers": {
    "troubleshooting": {
      "type": "stdio",
      "command": "./tscli",
      "args": ["mcp"]
    }
  }
}

Copilot-only fields ("tools", "id") should not be written for Cursor.

Environment (please complete the following information)

• OS:
• Python Version:
• APM Version:
• Cursor Version:

Logs

Actual .cursor/mcp.json generated by APM (broken in Cursor):

{
  "mcpServers": {
    "troubleshooting": {
      "type": "local",
      "tools": ["*"],
      "id": "",
      "command": "./tscli",
      "args": ["mcp"]
    }
  }
}

After manual fix (works):

{
  "mcpServers": {
    "troubleshooting": {
      "type": "stdio",
      "command": "./tscli",
      "args": ["mcp"]
    }
  }
}

Additional context

Scope. This is an APM adapter bug — the consumer package's apm.yml is correct; only the Cursor output is wrong.

Suggested fix. Override _format_server_config (and/or the type mapping) in CursorClientAdapter so that:

• type is set to "stdio" for stdio transports (and "http" for HTTP/SSE transports, per Cursor docs);
• Copilot-only fields (tools, id) are not emitted.

Workaround for users today. After apm install --client cursor, edit .cursor/mcp.json and replace "type": "local" with "type": "stdio"; optionally drop "tools" and "id".

[chaobo8484]

I'll fix this soon.

[chaobo8484]

https://github.com/microsoft/apm/pull/869

[chaobo8484]

I have fixed it and am waiting for review.

[github-actions]

Triage decision

accept

Proposed labels

theme/portability
area/mcp-config
type/bug
status/accepted
priority/high
good first issue

Milestone

0.9.4

Suggested next action

Override _format_server_config in CursorClientAdapter to emit "type": "stdio" (or "type": "http") and omit Copilot-only fields ("tools", "id"), following the Cursor MCP documentation schema.

Suggested issue comment

Excellent bug report -- you have identified the root cause, the fix, and provided a working minimal reproduction. This is exactly what makes a bug report immediately actionable.

The fix is confirmed: `CursorClientAdapter` should override `_format_server_config` to produce Cursor's documented schema:

- `"type": "stdio"` for stdio servers (not `"local"`)
- `"type": "http"` for HTTP servers
- No `"tools"` field
- No `"id"` field

The `_raw_stdio` path should also be reviewed to ensure it does not inherit any other Copilot-specific fields via the parent class.

A test case for `CursorClientAdapter._format_server_config` should be included in the PR to prevent regression -- `tests/unit/test_cursor_mcp.py` already has the pattern for asserting against the Cursor schema.

If you would like to submit the PR, the scope is well-defined and this would be a very welcome first contribution. The fix is localized to `src/apm_cli/adapters/client/cursor.py`.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The user task is "install an MCP server for Cursor and have it work." Currently, apm install --client cursor generates a .cursor/mcp.json that silently fails to register the MCP server because the schema is wrong ("type": "local" vs. Cursor's required "type": "stdio"). The user must manually fix the file every time. This is a clear and severe DX failure for a core use case.

Supply Chain Security Expert -- Risk-Surface Reviewer

The MCP adapter writes to .cursor/mcp.json. The bug is about schema correctness, not a security issue per se. The fix must not introduce any path traversal or credential exposure. No broader supply-chain risk surface beyond the standard adapter correctness requirement. theme/portability (Cursor-specific adapter behavior) is the primary theme.

OSS Growth Hacker -- Contributor-Tone Reviewer

denifilatoff has author_association: NONE -- this is their first or one of very few interactions with microsoft/apm. The bug report is exceptional: root cause identified, suggested fix provided, working reproduction steps, before/after JSON examples. The response should acknowledge the exceptional quality of the report explicitly, confirm the fix direction immediately, and extend a warm invitation to submit the PR. This is a natural good first issue since the author has already done all the investigation.

Python Architect -- Architecture Reviewer

Not activated -- the fix is localized to CursorClientAdapter._format_server_config override. No cross-cutting design decision is needed; the Cursor schema is documented and the fix is a straightforward method override. The existing test pattern in tests/unit/test_cursor_mcp.py covers the regression case.

Doc Writer -- Documentation Reviewer

Not activated -- this is a bug fix that restores correct behavior; no new user-facing documentation is needed. The Cursor docs link in the issue body confirms the expected schema.

APM CEO -- Triage Arbiter

High-severity bug with a confirmed fix and an exceptional report from a new contributor. Accept at priority/high for 0.9.4: MCP servers silently failing in Cursor is a critical failure for the Cursor integration story. Growth Hacker recommendation: the warm invitation to submit the PR is strategic -- this contributor has already done the investigation and the implementation is a one-method override.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": "theme/portability",
  "areas": ["area/mcp-config"],
  "type": "type/bug",
  "status": "status/accepted",
  "priority": "priority/high",
  "preserved_labels": ["good first issue"],
  "milestone": "0.9.4",
  "next_action": "Override _format_server_config in CursorClientAdapter to emit type:stdio/http and omit Copilot-only fields, with a regression test in tests/unit/test_cursor_mcp.py.",
  "comment_markdown": "Excellent bug report -- you have identified the root cause, the fix, and provided a working minimal reproduction. This is exactly what makes a bug report immediately actionable.\n\nThe fix is confirmed: `CursorClientAdapter` should override `_format_server_config` to produce Cursor's documented schema:\n\n- `\"type\": \"stdio\"` for stdio servers (not `\"local\"`)\n- `\"type\": \"http\"` for HTTP servers\n- No `\"tools\"` field\n- No `\"id\"` field\n\nThe `_raw_stdio` path should also be reviewed to ensure it does not inherit any other Copilot-specific fields via the parent class.\n\nA test case for `CursorClientAdapter._format_server_config` should be included in the PR to prevent regression -- `tests/unit/test_cursor_mcp.py` already has the pattern for asserting against the Cursor schema.\n\nIf you would like to submit the PR, the scope is well-defined and this would be a very welcome first contribution. The fix is localized to `src/apm_cli/adapters/client/cursor.py`."
}

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel · ● 2.3M · ◷