For Codex
Give Codex the request that broke production
Most observability tools hand your agent sampled spans and error strings. monoscope keeps every request and response, yours and your suppliers', so Codex reads the payload that failed before it edits a line.
01 · Why monoscope
Your agent reads the payload, not a guess
Code and stack traces tell an agent what could have happened. The stored request and response tell it what did. monoscope keeps both for every call your service receives and every call it makes to a supplier, unsampled, next to the logs, traces and metrics around it.
One stored call from 07:52, as Codex gets it back
resource.service.name orders-service
attributes.http.request.method POST
attributes.url.full https://api.acme-logistics.com/v1/shipments
attributes.http.response.status_code 200
body.request_body {"order_id":"ord_8812","service_level":"standard"}
body.response_body {"status":"acknowledged","shipment_id":"shp_8812"}
-
Unsampled, bodies included
Every request and response is kept with its headers and body. Bodies don't add to your event count or your bill.
-
Your suppliers' calls too
Calls out to Stripe, Acme or any third-party API are stored the same way, so the agent can show what they sent back.
-
Breaking changes, already flagged
When a response drops a field or changes a type, monoscope opens an issue. The agent finds it with list_issues instead of rediscovering it.
-
One key for all of it
Logs, traces, metrics, requests, issues, monitors and dashboards answer to the same API key and the same query language.
02 · Set it up
One command, then ask
Register the server with Codex and point it at the environment variable that holds your API key. Run /mcp in Codex to see the monoscope tools.
terminal
# An API key from Settings → API Keys in monoscope
export MONOSCOPE_API_KEY=...
codex mcp add monoscope --url https://api.monoscope.tech/api/v1/mcp \
--bearer-token-env-var MONOSCOPE_API_KEY
-
Scoped to one project
The key carries the project, so there's no project id to pass. Give each person their own key.
-
Nothing to run
The server is hosted at api.monoscope.tech. No binary, no container, no process to keep alive.
-
Or edit config.toml
The same entry in ~/.codex/config.toml is a [mcp_servers.monoscope] table with url and bearer_token_env_var.
03 · What it can call
Your production data, as tools
The tools come from the monoscope API, plus three that bundle a whole investigation into one call. New API endpoints show up as tools with nothing to update on your side.
-
Search every request and log
search_events runs a KQL query over logs, spans and stored request and response bodies. get_schema and list_facets tell it which fields exist.
-
Find what's failing
find_error_patterns ranks what's growing this hour. list_issues and analyze_issue return an issue with a written diagnosis.
-
Read metrics
query_metrics runs the same queries as your dashboards, with rate and increase for counters.
-
Change monitors and dashboards
Create, mute and resolve monitors, or apply a dashboard from YAML. Your Codex approval mode decides whether it asks before each call.
04 · While you work
Ask about production without leaving the terminal
The questions you'd otherwise answer by opening three dashboards. Codex asks monoscope mid-task, gets the records back and keeps working.
-
"What did Acme return for order 8812?"
Finds the outbound call by its attributes and returns the stored response body.
-
"Did my last deploy slow down checkout?"
Compares p95 latency per endpoint before and after the new service version.
-
"Which endpoints started failing in the last hour?"
Ranks the new error patterns and lists the endpoints and messages behind them.
-
"Alert me if checkout errors pass 50 in five minutes."
Creates the monitor and returns its link. Ask again to mute it.
05 · Skills
Playbooks for the jobs you repeat
The monoscope skills give Codex a playbook for each job. They drive the monoscope CLI in your shell, so the same steps work in CI and over SSH.
terminal
npx skills add monoscope-tech/skills
# The skills call the monoscope CLI
curl -fsSL https://monoscopehq.com/install.sh | sh
monoscope auth login
-
Investigate
"Look into the 500s in checkout-api." Finds the services involved, pulls the failing requests and the window around them, and summarises the cause.
-
Triage
"Do an on-call sweep." Reviews open issues, log patterns and monitors, then acknowledges, archives or mutes what's noise.
-
Manage
"Alert me when checkout errors pass 50." Writes monitors and dashboards as code you can keep in the repo.
-
Instrument
"Add tracing to this app." Adds OpenTelemetry and points the exporter at monoscope.
Questions
What does Codex need?
A monoscope project that's receiving data, and an API key from Settings → API Keys. Setup takes one command.
How is this different from other observability MCP servers?
An MCP server can only return what its tool kept. APM tools usually sample traces and don't store request or response bodies, so the agent gets an error string and a span. monoscope keeps the full request and response of every call, yours and your suppliers', so the agent can quote the payload that failed.
Can Codex change anything through monoscope?
Inside monoscope, yes: monitors, dashboards, issue status, teams and API keys all have tools. It can't reach your code or infrastructure through monoscope. Your Codex approval mode decides whether it asks before each call.
Does it see request bodies?
Yes, the ones monoscope stored. The SDKs redact the fields you list before anything leaves your app, so redacted values never reach monoscope or your agent.
What does it cost?
The free tier covers 10,000 events a day. Cloud is $29 a month with 20 million events included, then $1 per million. Request and response bodies don't count extra.
Does it work with self-hosted monoscope?
Yes. The MCP route ships in the open-source server at /api/v1/mcp, so point the URL at your own host. For the CLI and skills, set MONOSCOPE_API_URL.
