Generic MCP clients + OpenPets

What this integration does

The Generic MCP integration is for any assistant or editor that can launch a stdio MCP server. Instead of using a dedicated OpenPets setup flow, you add the OpenPets MCP command to your client's MCP configuration.

Tool	Purpose	Safety model
`openpets_status`	Checks whether OpenPets is reachable and which pet is targeted.	Read-only setup and health check.
`openpets_react`	Changes the pet reaction without showing text.	Use for silent states like thinking, testing, waiting, success, or error.
`openpets_say`	Shows one short visible speech bubble.	Rejects long, multiline, code-like, URL/path-like, or secret-looking messages.

Runtime is local. Your MCP client launches @open-pets/mcp, the MCP server uses @open-pets/client, and the client talks to the running OpenPets desktop app over local IPC.

Requirements

The OpenPets desktop app must be running for pet updates to work.
Your assistant or editor must support stdio MCP servers.
Node.js and npm must be available if you use the published npx command.

Generic MCP config

MCP clients use different root keys, but the command and arguments are the important part. Adapt the wrapper shape to your client's MCP format.

Generic stdio MCP serverjson

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

Some clients use a servers, mcp, or context_servers root instead of mcpServers. Keep the command as npx and the args as ["-y", "@open-pets/mcp@latest"] unless your client requires a different executable format.

Pet routing

By default, the MCP server targets the desktop app's default pet. Add --pet <pet-id> when you want this MCP process to request a specific installed pet.

Target a specific petjson

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

If the requested pet is available, OpenPets routes this MCP session to that pet.
If the requested pet is missing or unavailable, OpenPets falls back safely instead of breaking the assistant.
Explicit pet routing uses a short lease so agent pets can clean up automatically.

Recommended assistant instructions

MCP gives your assistant tools, but instructions teach it how to use those tools without leaking private context into a visible desktop bubble. Add a short rule block wherever your MCP client stores assistant instructions.

OpenPets assistant guidancemd

OpenPets MCP tools may be available.
Use openpets_status before using OpenPets or when debugging availability.
Use openpets_react for silent state changes like thinking, editing, testing, waiting, success, or error.
Use openpets_say only for short visible status messages.
Never send code, logs, command output, file paths, URLs, secrets, tokens, user prompts, or private data to openpets_say.
Do not spam every internal step.

Test the connection

After your MCP client loads the server, ask it to use OpenPets intentionally:

Test prompttext

Check OpenPets status. If it is available, send a short "connected" message and a waving reaction.

If your client exposes MCP tool calls in a debug panel, you should see openpets_status, openpets_react, and openpets_say.

Safety and behavior

Protection	Behavior
Short speech	`openpets_say` accepts messages up to 140 characters.
Single line	Multiline messages are rejected.
No code or logs	Code-like text, command output, URLs, file paths, and secret-looking text are rejected.
Best-effort availability	If the desktop app is closed, tools return an MCP error instead of crashing your assistant.

Keep the client wrapper client-specific

The portable part of this setup is the stdio command: npx -y @open-pets/mcp@latest. The client-specific part is its root key, so copy the command into the shape your client expects. The server exposes exactly openpets_status, openpets_react, and openpets_say, communicates with the desktop app over local IPC, and can use --pet as a fallback target. Its speech input is one line, 1–140 characters, and rejects sensitive-, path-, and code-like text. The MCP tools specification explains the tool surface; dedicated users can start with or instead.

Troubleshooting

The MCP tools do not appear

Restart or reload your MCP client after changing config.
Confirm the client supports stdio MCP servers.
Run npx -y @open-pets/mcp@latest --help in a terminal to confirm npm can resolve the package.
Check that your config uses the correct root key for your client.

The tools appear but OpenPets is unavailable

Open the OpenPets desktop app first.
Ask the assistant to call openpets_status.
If using --pet, confirm the pet id is installed with the OpenPets desktop app or the OpenPets CLI.

Should I use Generic MCP or a dedicated integration?

Use Claude Code or OpenCode pages when you use those tools; they include dedicated setup flows and managed instructions. Use Generic MCP when your tool supports MCP but OpenPets does not yet have a dedicated setup page for it.