OPP Observatory MCP

Read-only production observability for ChatGPT, designed to pair with C2C and Codex execution loops.

OPP Observatory gives an AI planning/review layer access to bounded runtime evidence—health, job status, latest-data summaries, approved logs, and deployment metadata—without giving that layer a production write path.

日本語: README.ja.md

Why this exists

Coding agents are increasingly good at changing code. Production debugging is a different problem: a useful diagnosis often needs runtime evidence, while handing a write-capable agent broad shell, SQL, or deployment access creates unnecessary risk.

OPP Observatory separates observation from execution:

                       ┌────────────────────────────┐
                       │        ChatGPT / LLM       │
                       │   analysis · plan · audit  │
                       └─────────────┬──────────────┘
                                     │
                      read-only      │      implementation handoff
                    runtime evidence │
                                     │
              ┌──────────────────────┴──────────────────────┐
              │                                             │
              ▼                                             ▼
   ┌─────────────────────┐                      ┌────────────────────────┐
   │ OPP Observatory MCP │                      │ C2C / codex-with-chatgpt│
   │   read-only tools   │                      │ bounded workspace bridge│
   └──────────┬──────────┘                      └────────────┬───────────┘
              │                                             │
       forced-command SSH                                   ▼
       / private adapter                              Codex / coding agent
              │                                      edit · test · review
              ▼
     production/runtime

The companion C2C project is here:

https://github.com/OPP-studio-macchino/codex-with-chatgpt

The intended loop is:

1. Observe the real runtime with OPP Observatory.

2. Inspect source/history with GitHub or a local workspace bridge.

3. Let ChatGPT produce a small, evidence-backed implementation handoff.

4. Send only the implementation task through C2C to Codex.

5. Let Codex edit and test in the workspace—not in production.

6. Re-observe runtime state with OPP Observatory and review the diff independently.

This makes the observation lane and the execution lane independently reviewable.

Related MCP server: system-brain-mcp

MCP tools

The public server exposes exactly five tool shapes:

All five tools advertise readOnlyHint: true and destructiveHint: false.

What it deliberately does not expose

• arbitrary shell execution;

• arbitrary SQL;

• arbitrary filesystem paths;

• INSERT, UPDATE, or DELETE database operations;

• git push;

• deployment or restart actions;

• package installation;

• a generic SSH terminal.

The public client sends only an allowlisted action plus a base64url-encoded JSON payload to a remote adapter. The remote side must validate the action and its parameters again.

Security model

The recommended production topology uses a dedicated SSH key whose authorized_keys entry is restricted to a forced command. The remote account should have only the minimum read permissions needed by the adapter.

Example shape:

restrict,command="/usr/local/libexec/opp-observer" ssh-ed25519 AAAA... observatory

Recommended controls:

• dedicated observer account or tightly constrained service account;

• forced command; no interactive shell;

• no PTY, agent, X11, or port forwarding;

• fixed action allowlist on both MCP and remote-adapter sides;

• bounded output and timeouts;

• secret-shaped value redaction before returning log excerpts;

• no production credentials stored in this repository;

• runtime evidence treated as untrusted data, never instructions.

See docs/security-model.md for the trust boundaries and residual risks.

OpenAI Secure MCP Tunnel

The server uses stdio, which works cleanly behind the official OpenAI Secure MCP Tunnel. The tunnel is the transport; it does not weaken the observer's read-only contract.

A deployment-specific tunnel config can point the main channel at the local stdio launcher. Keep API keys outside the repository and use file references or a secret manager.

In ChatGPT developer mode, create a custom plugin/app, choose Tunnel, select only the intended tunnel, and use No authentication when the tunnel is the authenticated transport and the local MCP itself does not advertise OAuth.

This repository does not contain tunnel IDs, API keys, production addresses, or private runtime evidence.

Quick start

Requirements:

• Node.js 20+

• pnpm via Corepack

• OpenSSH client

• a reviewed remote adapter implementing the action contract

git clone https://github.com/OPP-studio-macchino/opp-observatory-mcp.git
cd opp-observatory-mcp
corepack enable
pnpm install --frozen-lockfile
pnpm check

Configure only the observer target identity:

export OBS_SSH_HOST='observer.example.com'
export OBS_SSH_USER='observer'
export OBS_SSH_KEY="$HOME/.ssh/opp_observatory_ro_ed25519"
export OBS_REMOTE_COMMAND='observe'

Start the MCP server over stdio:

node dist/src/stdio.js

For production, supervise the process with your platform's service manager or the OpenAI tunnel runtime rather than an ad-hoc background shell.

Remote adapter contract

The MCP invokes SSH with this logical command shape:

observe <action> <base64url-json-payload>

Allowed actions are:

system-status
job-status
latest-data
log-search
deployment-info

A deployment adapter should map those actions to fixed, reviewable reads. A generic example is provided in remote/observer_example.py. Do not turn it into a generic command proxy.

Pairing with C2C + Codex

OPP Observatory and C2C solve different halves of the same maintenance workflow:

• Observatory answers: “What is actually happening in the runtime?”

• C2C answers: “What code/workspace evidence should ChatGPT inspect, and what bounded implementation task should Codex run?”

• Codex answers: “Can I implement and verify the requested change in the workspace?”

A suggested handoff is in docs/c2c-workflow.md.

The important design choice is that the production-observation tool never becomes the code-execution tool.

Validation status

The architecture behind this public repository has been exercised end-to-end against a private production workload using:

ChatGPT Web
  → custom OPP Observatory plugin
  → OpenAI Secure MCP Tunnel
  → local stdio MCP
  → forced-command SSH
  → read-only remote adapter

The public repository intentionally contains a generic adapter contract instead of the private deployment's hostnames, paths, log locations, database model names, or credentials.

This is an independently maintained community project. It is not affiliated with or endorsed by OpenAI.

Development

pnpm typecheck
pnpm test
pnpm build
pnpm audit --prod

CI runs type checking, unit/in-memory MCP tests, build, and a production dependency audit. CodeQL runs separately.

Project status and roadmap

The current focus is deliberately small: make read-only operational evidence easy to review and hard to accidentally turn into a write path.

See ROADMAP.md. Issues and security-minded contributions are welcome.

Security reports

Please follow SECURITY.md. Never include live credentials, private source, personal data, raw customer data, or unredacted production logs in a public issue.

License

MIT — see LICENSE.