---
title: Set up opsmcp
description: Connect a coding agent to the read-only Playyy observability MCP server.
canonical_url: https://opsmcp.sheji.dev/
md_url: https://opsmcp.sheji.dev/setup.md
mcp_url: https://opsmcp.sheji.dev/mcp
last_updated: 2026-08-21
---

# Set up opsmcp

> Connect a coding agent to read-only logs, errors, database health, deployments, and session replays across the Playyy dev, staging, and production environments.

## Instructions for coding agents

Set up an MCP server named `opsmcp` for the client that is currently running you.

- Use the Streamable HTTP endpoint `https://opsmcp.sheji.dev/mcp`.
- Use OAuth. Do not ask the user to create or paste a bearer token unless the OAuth flow cannot run, such as in headless CI.
- Preserve every existing MCP server when editing a configuration file. Merge the `opsmcp` entry; never replace the whole file.
- You may run the applicable setup command, but browser-based GitHub authorization requires the user to take over. Tell them when the browser opens and wait for them to finish.
- After changing configuration, tell the user if the current agent process must reconnect or start a new session before the new tools appear.

## Claude Code

Run:

```bash
claude mcp add --transport http --scope user opsmcp https://opsmcp.sheji.dev/mcp
```

Then open `/mcp`, choose `opsmcp`, and complete the GitHub sign-in.

## Codex

Run:

```bash
codex mcp add opsmcp --url https://opsmcp.sheji.dev/mcp
codex mcp login opsmcp
```

The second command opens the GitHub sign-in flow. If the current Codex session does not expose the new tools after login, start a new session.

## Cursor

Merge this entry into `~/.cursor/mcp.json` without deleting other servers:

```json
{
  "mcpServers": {
    "opsmcp": {
      "url": "https://opsmcp.sheji.dev/mcp"
    }
  }
}
```

Then open Cursor's MCP settings, connect `opsmcp`, and complete the GitHub sign-in.

## Other MCP clients

Create a remote or Streamable HTTP MCP server named `opsmcp` with URL `https://opsmcp.sheji.dev/mcp`. Leave static authorization headers empty and use the client's OAuth or Connect action. Configuration shapes differ between clients, so follow that client's remote HTTP MCP format rather than guessing one.

## Verify the connection

After authentication, call `catalog_services` once with:

```json
{
  "env": "dev",
  "purpose": "Verify opsmcp setup and inspect the available dev services"
}
```

A successful response returns the environment's service catalog. Every operational call requires `env` (`dev`, `staging`, or `prod`) and a concrete `purpose` of at least 10 characters. Reuse an optional `investigation_id` across calls that belong to the same investigation.

## Authentication and safety

OAuth redirects to GitHub and is restricted to active members of the configured organization. The MCP client stores the resulting access token; it should not be copied into a project file or chat.

opsmcp is read-only: it cannot deploy code, mutate providers, or execute SQL against application tables. Results are bounded investigation evidence, so honor the completeness and sampling notes returned by each tool.

When a tool returns a `download.curl` command, run that command exactly as given. It contains a short-lived bearer grant scoped to one payload and does not require access to the MCP client's OAuth token or an `OPSMCP_TOKEN` environment variable. The endpoint is intentionally not exposed as a separate URL because a bare request cannot authenticate. Treat the command as sensitive until its stated expiry and do not copy it into project files.

For headless CI or an MCP client that cannot complete OAuth, create a manually managed token from `https://opsmcp.sheji.dev/tokens` and configure it as an `Authorization: Bearer` header in that client's secret storage.

## Troubleshooting

- Initial `401 Unauthorized`: expected during OAuth discovery; use the client's login or Connect action.
- GitHub access denied: confirm the user is an active member of the required GitHub organization.
- Server is configured but tools are missing: reconnect the MCP server or start a new agent session.
- Tool input is rejected: include a specific `purpose`, the correct `env`, and only parameters declared by the tool schema.