mcp-setup

---
name: mcp-setup
description: >-
  Connect, scaffold, configure, and verify MCP servers in Cursor (mcp.json,
  stdio/HTTP transport, minimal server templates, smoke test with mcp-tester).
  Use when the user mentions MCP, Model Context Protocol, mcp.json, Cursor MCP,
  adding tools for the agent, scaffolding an MCP server, or debugging MCP setup.
---

# MCP Setup Wizard

Help the user **wire an MCP server into Cursor** end-to-end: choose transport, write config, optionally scaffold a minimal server, then verify tools work.

## Defaults

- Prefer **stdio** for local servers (simplest).
- Config path: project `.cursor/mcp.json` (team-shareable) unless the user asks for global Cursor MCP settings.
- Never commit secrets; use env var references in config.
- After config changes, tell the user to **reload MCP / restart Cursor** if tools do not appear.
- Verify with [mcp-tester](https://github.com/kou-123/mcp-tester) when available: `npx mcp-tester -- <server command>`.

## Workflow

Copy and track:

```text
MCP setup progress:
- [ ] 1. Clarify goal (use existing server vs build new)
- [ ] 2. Pick transport (stdio default; HTTP only if remote/shared)
- [ ] 3. Write mcp.json (no secrets in plain text)
- [ ] 4. Scaffold server only if needed
- [ ] 5. Verify tools/list + one tools/call
- [ ] 6. Document how to run / reload for the user
```

### 1. Clarify goal

Ask only what blocks progress (max 1–2 questions):

- **Existing server?** → need start command (and args), or HTTP URL  
- **New server?** → language preference (default **Node.js** stdio)  
- **Project vs personal config?** → default **project** `.cursor/mcp.json`

### 2. Pick transport

| Situation | Transport |
|-----------|-----------|
| Local CLI / `node` / `python` / `npx` server | **stdio** |
| Remote hosted MCP endpoint | Streamable HTTP (see [reference.md](reference.md)) |
| Unsure | **stdio** |

### 3. Write `mcp.json`

Create or merge `.cursor/mcp.json`. Use templates in [templates/](templates/).

**stdio shape:**

```json
{
  "mcpServers": {
    "demo": {
      "command": "node",
      "args": ["path/to/server.js"],
      "env": {
        "API_KEY": "${env:API_KEY}"
      }
    }
  }
}
```

Rules:

- Absolute paths only when necessary; prefer repo-relative paths from project root.
- For `npx` servers: `"command": "npx"`, `"args": ["-y", "package-name", ...]`.
- Put API keys in environment variables, not committed files.
- If merging into existing JSON, preserve other servers.

### 4. Scaffold (only when building new)

If the user needs a new server:

1. Add a minimal stdio server from [templates/demo-server.js](templates/demo-server.js) (or Python variant in reference).
2. Implement at least one tool with a clear `inputSchema`.
3. Log only on **stderr**; **stdout** is for MCP JSON-RPC only.

### 5. Verify

Run in order:

```bash
# A) Protocol-level (recommended)
npx mcp-tester -- <the same command/args as in mcp.json>

# B) Or built-in demo of mcp-tester
npx mcp-tester demo
```

Pass criteria:

- Handshake succeeds (`initialize`)
- `tools/list` returns expected tools
- One `tools/call` returns a non-error result

If mcp-tester is unavailable, smoke with a tiny Node client or ask the user to open Cursor MCP logs after reload.

### 6. Finish

Tell the user:

1. Where config was written  
2. Exact server start command  
3. How to reload MCP in Cursor  
4. Which tools should appear  
5. Optional: link to mcp-tester for future debugging  

## Common failures

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| No tools in Cursor | Config path wrong / need reload | Fix `.cursor/mcp.json`, reload MCP |
| Server exits immediately | Crash on startup | Run command in terminal; check stderr |
| Parse / JSON-RPC errors | Logs written to stdout | Move logs to stderr |
| Missing API key | Env not passed | Set env in shell or `mcp.json` `env` |
| Works in mcp-tester, not Cursor | Different command/cwd | Align Cursor args with the working command |

## Additional resources

- Config & transport details: [reference.md](reference.md)
- Copy-paste scenarios: [examples.md](examples.md)
- Templates: [templates/](templates/)