Cursor MCP Sidecar Quick Start

Cursor MCP Sidecar Quick Start

Connect AIWG to Cursor as an MCP sidecar for unrestricted workflow access.

Why a sidecar? Cursor is IDE-integrated and cannot be spawned from the CLI. The MCP sidecar (`aiwg mcp serve`) runs as a user-level shell process with full filesystem permissions. Cursor connects to it via MCP and calls whitelisted AIWG tools — giving you unrestricted artifact management without leaving the IDE.

Architecture

Cursor IDE (host)
  ├── AI panel, chat, code generation
  ├── Built-in tools
  └── MCP connection
        └── AIWG MCP Server (sidecar)
              └── .aiwg/ artifacts, workflows, templates

Cursor owns: conversation, code editing, file management.

AIWG owns: workflow execution, artifact output in `.aiwg/`, template rendering, agent definitions.

MCP is the seam. Cursor calls AIWG tools via the protocol boundary — no filesystem coupling, no context duplication.

Prerequisites

  • Cursor installed (https://cursor.sh)
  • AIWG installed (`npm install -g aiwg`)
  • A project with `aiwg use sdlc --provider cursor` already deployed

Part 1: Install MCP Configuration

# Generate .cursor/mcp.json with AIWG server config
aiwg mcp install cursor

This creates or merges into `.cursor/mcp.json`:

{
  "mcpServers": {
    "aiwg": {
      "command": "aiwg",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

Note: Cursor supports both project-level (`.cursor/mcp.json`) and global (`~/.cursor/mcp.json`) MCP configuration. The project-level config is recommended for AIWG so it's version-controlled with your project. Cursor also supports `${env:NAME}`, `${workspaceFolder}`, and `${userHome}` variable interpolation in config values.


---

## Part 2: Configure Tool Whitelist (Recommended)

For optimal context usage, limit the exposed tools. Edit `.cursor/mcp.json`:

{ "mcpServers": { "aiwg": { "command": "aiwg", "args": ["mcp", "serve"], "tools": { "include": [ "discover", "command-run", "artifact-read", "artifact-write", "template-render", "agent-list" ], "prompts": false, "resources": false } } } }


**Why whitelist?** Each MCP tool adds schema overhead to the context window. The lean whitelist keeps AIWG's footprint bounded while preserving discovery, CLI dispatch, artifact IO, templates, and agents.

> **Cursor 2.4+**: Agents now discover and load MCPs only when needed, reducing token usage automatically. The whitelist is still recommended for explicit control.

A pre-configured template is available at `agentic/code/frameworks/sdlc-complete/templates/cursor/cursor-mcp-minimal.json`.

---

## Part 3: Verify the Connection

1. Restart Cursor (or reload the project)
2. Open the AI panel
3. Ask: "What AIWG tools are available?"
4. Cursor should list the lean whitelisted tools

---

## Part 4: Run Your First Workflow

Ask the Cursor AI panel:

Create an architecture decision record for choosing REST over GraphQL for our API. Save it as an AIWG artifact.


**What should happen:**

1. Cursor calls `command-run`, `template-render`, or `artifact-write` via MCP
2. AIWG creates the artifact in `.aiwg/architecture/`
3. Cursor receives the result

**Verify:**

ls .aiwg/architecture/


---

## Part 5: Context Budget

Understanding the token budget helps you configure the whitelist appropriately.

### With lean whitelist (recommended)

| Component | Tokens |
|---|---|
| Cursor system prompt | ~2,000 |
| AIWG MCP schema (lean tools) | bounded |
| **Total AIWG overhead** | **~3,000** |

### Without whitelist (full surface)

| Component | Tokens |
|---|---|
| Cursor system prompt | ~2,000 |
| AIWG MCP schema (core + opt-in toolsets) | larger |
| **Total AIWG overhead** | **~12,000** |

The lean whitelist materially reduces MCP context overhead, leaving more room for code, conversation, and artifact content. Enable `AIWG_MCP_TOOLSETS=flows` when you need `flow-list`, `flow-show`, and `flow-run`.

---

## Part 6: Advanced — Enable Prompts

After the basic integration is stable, enable AIWG workflow prompts for richer access:

{ "mcpServers": { "aiwg": { "command": "aiwg", "args": ["mcp", "serve"], "tools": { "include": [ "discover", "command-run", "artifact-read", "artifact-write", "template-render", "agent-list" ], "prompts": true, "resources": false } } } }


A pre-configured template is available at `agentic/code/frameworks/sdlc-complete/templates/cursor/cursor-mcp-full.json`.

Only enable prompts after Part 4 is working reliably.

---

## Validation Checklist

| Check | Action | Expected |
|---|---|---|
| Connectivity | Ask Cursor "list AIWG tools" | Lean tools listed |
| Artifact write | Ask for a requirements doc | File appears in `.aiwg/` |
| Artifact read | Ask to read an artifact | Uses `artifact-read` |
| Failure mode | Stop `aiwg mcp serve`, try again | Graceful error message |

---

## Troubleshooting

**AIWG tools not visible:**

- Verify `aiwg mcp serve` runs successfully standalone
- Check `.cursor/mcp.json` syntax (JSON is whitespace-sensitive)
- Restart Cursor after config changes

**Context filling up:**

- Verify the tool whitelist is configured
- Set `"resources": false` to suppress resource schemas
- Confirm `"prompts": false` until the baseline integration is stable

**Artifacts not appearing:**

- Ensure AIWG is initialized in the project (`aiwg use sdlc --provider cursor`)
- Verify the working directory matches the project root
- Check that `artifact-write` is in the tool whitelist

---

## Cloud Agent MCP Support

Cursor Cloud Agents (formerly Background Agents) **fully support MCP servers**. This means AIWG workflows can run in cloud agent mode:

1. Configure your MCP server in the Cloud Agent environment at cursor.com/dashboard/cloud-agents
2. Both HTTP and stdio transports work in Cloud Agent VMs
3. OAuth is supported for authenticated MCP servers

This enables asynchronous AIWG workflow execution without needing a local terminal session.

---

## MCP Debugging

If MCP tools aren't working:

1. Open Output panel: `Cmd+Shift+U` (Mac) / `Ctrl+Shift+U` (Windows/Linux)
2. Select "MCP Logs" from the dropdown
3. Check for connection errors or tool registration issues
4. Servers can be toggled on/off through Settings without removal

---

## Related Resources

- [Cursor Quick Start](cursor-quickstart.md) — Basic AIWG + Cursor integration
- [Cursor Quickstart](cursor-quickstart.md)
- [Hermes MCP Sidecar](hermes-quickstart.md) — Reference sidecar implementation
- [AIWG MCP server reference](../cli-reference.md#mcp)