Cursor + OpenPets

What this integration does

The Cursor integration gives Cursor the OpenPets MCP tools and an optional short project rule that teaches Cursor when to use them. It has one MCP layer and one optional rules layer; you can install either or both.

Part	Required?	What it gives Cursor
MCP server	Yes	Tools named `openpets_status`, `openpets_react`, and `openpets_say` via `@open-pets/mcp`.
Project rules	Optional	A short `.mdc` rule that tells Cursor when to use the OpenPets tools and what never to put in pet messages.
Hooks / lifecycle reactions	Not yet	Ambient Cursor hooks are a future phase and intentionally not written until a validation spike is complete.

Runtime is local. Cursor launches @open-pets/mcp as a stdio MCP server, the server uses @open-pets/client, and the client talks to the running OpenPets desktop app over local IPC. If OpenPets is closed, Cursor keeps working; pet updates are best-effort feedback.

Quick install

In the OpenPets desktop app, open Integrations and use the Cursor card. Install global setup writes the global Cursor MCP entry for your user account, and Configure opens the detail panel for pet routing, JSON preview, and remove actions.

Install global setup adds the openpets MCP server to ~/.cursor/mcp.json.
Configure opens advanced status, pet routing, project rules preview, and remove controls.
Restart Cursor, reload the window, or start a fresh chat if OpenPets tools do not appear immediately.

Desktop setup is global and can affect every Cursor project on that machine. For repository-specific setup or to add the project rule, use the CLI commands below.

MCP connection

MCP is the main Cursor-to-OpenPets bridge. OpenPets writes a single MCP entry named openpets; unrelated MCP servers and top-level fields in your Cursor config are preserved.

Tool	Purpose	When Cursor should use it
`openpets_status`	Checks whether the OpenPets desktop app is reachable and which pet is targeted.	Before using OpenPets, or when debugging setup.
`openpets_react`	Changes the pet reaction without showing text.	For silent state changes like thinking, editing, testing, waiting, success, or error.
`openpets_say`	Shows one short visible speech bubble.	For meaningful progress, blockers, completion, or review handoff.

Global vs project MCP config

Cursor merges global and project MCP config. When both define an openpets server, the project entry wins for that workspace. OpenPets always uses the server name openpets so you can override a global default per repository.

Setup style	Best for	File
Global desktop setup	Personal machine-wide Cursor setup.	`~/.cursor/mcp.json`
Project-local CLI setup	Repos that should explicitly carry OpenPets setup.	`<project>/.cursor/mcp.json`

Expected MCP entry

~/.cursor/mcp.json or <project>/.cursor/mcp.jsonjson

{
  "mcpServers": {
    "openpets": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@open-pets/mcp@latest", "--pet", "<pet-id>"]
    }
  }
}

If no pet is selected, --pet <pet-id> is omitted and OpenPets routes to the desktop default pet. OpenPets pins a specific @open-pets/mcp version when it writes the entry; the @latest shown above is the readable equivalent for manual setup.

Project setup with the CLI

Project MCP onlybash

npx -y @open-pets/cli@latest configure --agent cursor --pet <pet-id>

Project MCP from another directorybash

npx -y @open-pets/cli@latest configure --agent cursor --cwd /path/to/project --pet <pet-id>

--pet is optional. If omitted, the CLI may prompt from installed pets via the running desktop app.

Optional project rules

Cursor rules are prompt guidance, not lifecycle hooks. The OpenPets rule tells Cursor when and how to use the MCP tools safely. It is optional and project-local only; OpenPets does not edit Cursor's user or global rules settings.

Install or update the project rule onlybash

npx -y @open-pets/cli@latest configure --agent cursor --rules-only

Install MCP and rules togetherbash

npx -y @open-pets/cli@latest configure --agent cursor --pet <pet-id> --with-rules

Remove only the managed rulebash

npx -y @open-pets/cli@latest configure --agent cursor --remove-rules

--rules-only and --remove-rules do not require a pet selection or the OpenPets desktop app to be running. The rule file is written to:

Rule pathtext

<project>/.cursor/rules/openpets.mdc

Rule content

.cursor/rules/openpets.mdcmdc

---
description: Use OpenPets MCP tools for lightweight coding-status feedback.
---
<!-- OPENPETS:CURSOR_RULES:START -->
OpenPets status feedback
You may use the OpenPets MCP tools as a brief, safe status channel during meaningful coding work.
Use openpets_say sparingly for major milestones, blocking states, completion, or when review is needed.
Prefer openpets_react over speech for lightweight progress such as thinking, working, testing, success, or error.
Keep messages short, user-facing, and safe.
Do not send prompts, tool input/output, code, logs, stack traces, credentials, private file contents, URLs, file paths, or other sensitive content through OpenPets.
Do not spam every internal step; use OpenPets only for meaningful progress changes and continue normally if a status update is unnecessary.
If OpenPets is unavailable, continue the coding task without failing.
<!-- OPENPETS:CURSOR_RULES:END -->

OpenPets intentionally does not set alwaysApply: true so the rule stays out of every prompt by default. Cursor will include the rule when the workspace is open; a new chat may be needed for changes to be picked up.

Force, conflicts, and backups

OpenPets refuses to overwrite unknown user content by default. When the MCP entry or rule file looks different from what OpenPets manages, status is reported as custom or conflict and nothing is rewritten without an explicit opt-in.

Force replace, scopedbash

npx -y @open-pets/cli@latest configure --agent cursor --rules-only --force
npx -y @open-pets/cli@latest configure --agent cursor --pet <pet-id> --with-rules --force

MCP replacement touches only mcpServers.openpets.
Rules replacement touches only .cursor/rules/openpets.mdc.
Backups are created before any replace or remove operation.
--with-rules preflights MCP and rules together so a half-applied setup is avoided.

Pet routing

Without a selected pet, Cursor targets the OpenPets desktop default pet. With a selected pet, OpenPets adds --pet <pet-id> to the MCP command so Cursor targets that companion.

Runtime pathtext

Cursor
  -> OpenPets MCP server (@open-pets/mcp)
  -> @open-pets/client
  -> OpenPets desktop local IPC
  -> default pet or selected agent pet

No selected pet: MCP targets the desktop default pet.
Selected pet: the MCP args include --pet <pet-id>.
Explicit pet sessions use short leases so agent pets clean up automatically.
If a requested pet is missing or unavailable, OpenPets falls back safely instead of breaking Cursor.

Cursor behavior and caveats

Restart, reload, or new chat

Cursor MCP loading varies by version and environment. If OpenPets tools do not appear after install:

Start a new Cursor chat.
Reload the Cursor window.
Fully restart Cursor.
Verify Node and npm can run the configured npx command.

Rules are included as chat context, so changed rules may also need a new or refreshed chat to be picked up.

WSL, remote, and devcontainer

OpenPets desktop runs on the local OS and the MCP server reaches the desktop over local IPC. If Cursor runs MCP commands inside WSL, a remote host, or a devcontainer, the command may run somewhere that cannot reach the desktop app.

Cursor may show MCP connection failures.
openpets_status may report the desktop as unreachable.
The configured npx or node command may exist in one environment but not the one Cursor uses.

Workarounds depend on the environment. OpenPets does not currently write WSL or devcontainer-specific MCP entries automatically.

Safety and behavior

OpenPets treats Cursor config as user-owned. MCP and rules edits are scoped, audited, and reversible.

Protection	Behavior
Scoped MCP edits	Only `mcpServers.openpets` is read, written, replaced, or removed; unrelated servers and fields are preserved.
Scoped rules edits	Only `.cursor/rules/openpets.mdc` is touched. Other rule files and the `.cursor` directory itself are left in place.
Strict JSON	MCP config is read as strict JSON. Files that do not parse are classified as invalid instead of being rewritten.
Size limits	MCP config reads cap at 256 KiB. Rule reads cap at 64 KiB.
Safe writes	Atomic temp-file writes with rename, plus backups before any replace or remove.
Symlink rejection	Symlinked config files, non-regular files, unsafe parents, and dangling symlinks are refused.
Managed detection	Rules are treated as managed only when the OpenPets frontmatter and exactly one ordered marker pair are present; user-authored files become conflicts, not overwrites.
Preview redaction	The desktop preview shows only the OpenPets MCP entry; broader previews redact sensitive-looking fields.
No broad permissions	OpenPets never writes `~/.cursor/permissions.json` or adds broad MCP/tool allowlists.

Troubleshooting

Cursor does not show OpenPets tools

Start a new chat, reload the window, or fully restart Cursor.
Confirm OpenPets desktop is running and click Refresh on the Cursor detail panel.
Run npx -y @open-pets/mcp@latest --help in a terminal to confirm npm can resolve the package.
If Cursor runs in WSL, remote, or a devcontainer, see the caveats above.

OpenPets reports the MCP entry as custom or conflicted

A custom or conflicted status means the existing openpets entry, the MCP config file, or the rule file does not match what OpenPets manages. OpenPets leaves it alone. Use Replace in the detail panel, or the --force CLI flag, only when you want OpenPets to recreate its managed entry or file.

Wrong pet appears

Re-run setup with the pet ID you want. If that pet is not installed, invalid, or broken, the desktop app falls back to the default pet.

Refresh project setupbash

npx -y @open-pets/cli@latest configure --agent cursor --pet <pet-id> --cwd . --force

Remove or reset

Remove the global MCP entry from the desktop detail panel. Remove the project rule with npx -y @open-pets/cli@latest configure --agent cursor --remove-rules. Both operations create backups before touching managed content.

What is next

Cursor MCP and project rules are complete. The next phase would be Cursor hooks for ambient lifecycle reactions, similar to Claude hooks or the OpenCode plugin event mapper. Hooks are intentionally not written yet — they need a validation spike covering hook config paths, payload schema, stdout behavior, timeouts, fail-open vs fail-closed semantics, and execution location across local, WSL, remote, and devcontainer setups.