Connect Your AI Coding Agent to Oack Monitoring

AI coding agents are becoming a natural part of the development workflow. Where they shine is not the obvious “something is on fire” scenario — your alerting handles that. It’s the slower, harder work: correlating latency spikes across multiple monitors to find a common cause, sifting through hundreds of probe results to spot a pattern, or cross-referencing TCP metrics with HTTP timing to figure out why a specific endpoint degrades under load. These are tasks where an agent with access to your monitoring data can save you hours of manual digging.

Oack supports three ways to give your AI agent access to monitoring data:

1. MCP Server — native Model Context Protocol integration with 53 read-only tools
2. oackctl CLI — a command-line tool any agent can invoke via shell
3. llms.txt — structured context files indexed by Context7 for documentation-aware assistance

This guide covers setup for each approach across the most popular AI coding tools.

MCP Server: native integration

The Model Context Protocol is an open standard for connecting AI agents to external tools and data sources. Oack’s MCP server exposes 53 read-only tools that let your agent query monitors, probes, latency metrics, alerts, SSL expiration, TCP statistics, and more — without leaving your editor.

Claude Code

Add to your project’s .mcp.json (or global ~/.claude.json):

{
  "mcpServers": {
    "oack": {
      "type": "http",
      "url": "https://api.oack.io/mcp/"
    }
  }
}

Important: Claude Code expects "type": "http" for Streamable HTTP servers, not "type": "streamable-http" or "type": "sse".

Restart Claude Code. On the first tool call, your browser opens for OAuth authorization. Sign in with Google or GitHub, pick which accounts and teams the agent can access, click Authorize, and you’re done. The token is cached automatically — subsequent sessions reconnect silently.

To allow Claude to use all Oack tools without per-call permission prompts:

/permissions add mcp__oack__* "allow all Oack MCP tools"

Claude Desktop

Add to claude_desktop_config.json (Settings > Developer > Edit Config):

{
  "mcpServers": {
    "oack": {
      "type": "http",
      "url": "https://api.oack.io/mcp/"
    }
  }
}

Restart Claude Desktop. Same OAuth flow — browser opens, you approve, agent gets access.

Cursor

Open Cursor Settings > MCP Servers > Add new server:

• Name: oack
• Type: http
• URL: https://api.oack.io/mcp/

Cursor will handle the OAuth flow when you first invoke an Oack tool.

Windsurf

Add to your Windsurf MCP configuration:

{
  "mcpServers": {
    "oack": {
      "type": "http",
      "url": "https://api.oack.io/mcp/"
    }
  }
}

Any MCP-compatible client

Any client that supports MCP Streamable HTTP transport can connect. Point it at:

https://api.oack.io/mcp/

The server publishes OAuth metadata at /.well-known/oauth-authorization-server for automatic discovery.

Authentication: OAuth 2.0 + PKCE

You never create an API key or copy a token. The MCP flow uses OAuth 2.0 with PKCE — the same protocol that powers “Sign in with Google” buttons, adapted for machine-to-machine communication:

1. Your MCP client discovers OAuth endpoints automatically
2. It registers itself once (per RFC 7591)
3. A browser tab opens to the Oack consent screen
4. You sign in with Google or GitHub and explicitly select which accounts and which teams the agent may access
5. The client receives a token scoped to exactly those resources — nothing more

This is the critical point: there is no master key that opens all the doors. Each MCP connection is scoped to the accounts and teams you approved on the consent screen. If you have a personal account and a production account, you can grant the agent access to one without exposing the other. If your production account has five teams, you can share two and keep the rest invisible to the agent.

The consent screen is not a one-time “accept all” dialog — it’s a fine-grained access control step that you go through once per MCP client. You can revoke or change the scope at any time by removing and re-adding the MCP server entry in your client config.

Token refresh is automatic. Access tokens expire after 1 hour and are refreshed silently. You’ll only see the consent screen again if you haven’t used the connection in 90+ days.

What tools are available?

All 53 tools are read-only — the agent can query data but cannot modify monitors, alert channels, or settings.

Category	Tools	What they cover
Accounts & Teams	7	List accounts, team members, subscription info
Monitors	4	Status, config, p50/p95/p99 latency, SSL/domain expiration
Probes	3	Recent check results, full probe detail, time-range aggregation
Alerts	3	Alert channels, recent events (DOWN/RECOVERY), channel-monitor links
Checkers & Geo	3	Checker nodes, regions, coordinates
Overview	1	High-level summary across all teams
Plus	32	Timeline, traces, comments, chart events, shares, status pages, CF integrations, and more

oackctl: CLI for any agent

Not every coding agent supports MCP. But almost every agent can run shell commands. oackctl is the official Oack CLI with full API coverage — 50+ commands that any agent can call via bash, exec, or subprocess.

Installation

Homebrew (macOS / Linux):

brew tap oack-io/tap
brew install oackctl

Shell script:

curl -sSfL "https://raw.githubusercontent.com/oack-io/oackctl/refs/heads/main/install-oackctl.sh" | bash

Authentication

# Interactive (opens browser)
oackctl login

# Or set a static token for CI/scripting
export TT_TOKEN=<jwt>

AI agent reference: SKILL.md

The oackctl repository includes a SKILL.md file — a complete reference designed specifically for AI agents. It lists every command, every flag, common workflows, and error codes. If your agent reads this file before using oackctl, it will know exactly how to construct the right command for any query.

Indexed by Context7

The oackctl documentation is indexed by Context7, which means any AI agent that uses Context7 as a context provider can discover and use oackctl documentation automatically. When your agent needs to look up how to query Oack, Context7 surfaces the relevant SKILL.md sections without you having to paste documentation manually.

llms.txt: structured context for any LLM

Oack publishes llms.txt and llms-full.txt following the llms.txt specification — a lightweight standard for providing LLM-friendly documentation.

• llms.txt — concise index: product overview, links to docs, tools, pricing, and contact info
• llms-full.txt — expanded version with complete documentation sections, API reference, and tool descriptions

These files are designed to be fetched and included in an LLM’s context window. If your agent supports WebFetch or has access to Context7, it can pull the latest Oack documentation on demand — no manual copy-paste required.

What can you ask?

Once your agent is connected (via MCP, oackctl, or context from llms.txt), here are practical questions you can ask during a coding session:

Real-world troubleshooting

This is where agents truly shine — correlating data across multiple probes to find a root cause that would take you much longer to piece together manually.

Prompt:

“Why is this monitor flapping? I’m getting TLS errors in one probe and no errors in the next one.”

The agent pulled the probe history, compared successful and failing probes, examined the resolved IPs and TLS certificate details across both, and identified the pattern in 34 seconds:

Root cause: DNS round-robin hitting a server with the wrong TLS certificate.

The domain resolved to multiple IPs (shared hosting or load balancer). Some backends served the correct TLS certificate, while others served a certificate for a completely different domain. The probes alternated almost every minute between:

• Success — hits a backend with the correct cert, gets HTTP 503 (~500 ms) — counted as UP since 503 was in the allowed status codes
• TLS failure — hits a backend that presents the wrong certificate — connection rejected before any HTTP response

The agent concluded: each DNS resolution lands on a different backend, and roughly half of them have a misconfigured certificate. It recommended checking which IPs the domain resolves to and identifying which ones serve the wrong cert — that server needs its TLS/SNI configuration fixed.

It also flagged a side issue: even the “successful” probes were returning 503, meaning the site itself was down or in maintenance — worth investigating once the TLS problem is sorted.

This is the kind of investigation that typically requires opening dozens of probe detail panels, comparing resolved IPs, reading TLS error messages, and mentally correlating the pattern. The agent did it by reading the probe data programmatically and spotting the alternating IP/certificate pattern across the full history.

Incident triage

“Is anything down right now?” The agent calls oack_status_overview → “All 12 monitors are up across 2 teams.”

“Show me the last 5 failed probes for api.example.com” The agent calls oack_probes_list with a status filter → lists each failure with timestamp, error message, and latency breakdown.

Performance investigation

“What’s the p95 latency for the payments API this week?” The agent finds the monitor via oack_monitors_list, then calls oack_monitor_metrics → “p95 latency for payments-api over the last 7 days is 342 ms.”

“Give me a latency breakdown for the last failing probe” The agent calls oack_probe_get → “DNS: 12 ms, Connect: 45 ms, TLS: 89 ms, TTFB: 2340 ms, Total: 2502 ms. The server took 2.3s to respond.”

Certificate and domain monitoring

“Is the SSL cert for example.com expiring soon?” The agent calls oack_monitor_expiration → “SSL certificate expires in 23 days (Mar 30). Issued by Let’s Encrypt.”

Team overview

“How many monitors does each team have and what’s their uptime?” The agent iterates through oack_teams_list and oack_monitors_list per team → builds a summary table with monitor counts and overall uptime percentages.

Using oackctl from the terminal

“Check the current status of our production monitors” The agent runs oackctl monitors list --team <id> --json and parses the output.

“Get the probe details for the last check on dashboard-api” The agent runs oackctl probes list --team <id> --monitor <id> --limit 1 --json followed by oackctl probes get --team <id> --probe <id> --json.

Choosing the right integration

Approach	Best for	Pros	Cons
MCP Server	Claude Code, Claude Desktop, Cursor, Windsurf	Native integration, structured tool calls, OAuth scoping, no CLI install needed	Requires MCP-compatible client
oackctl CLI	Any agent with shell access (GitHub Copilot, Aider, custom agents)	Works everywhere, full API coverage, scriptable	Requires install + auth, agent needs to parse output
llms.txt	Context-only use cases, documentation questions	Zero setup, always up to date	Read-only context, no live data queries

Pick one or combine them. MCP for native tool calls, oackctl when you need write operations or work outside an MCP client, and llms.txt for always-available product context.