MCP Server Setup

CheckUpstream exposes an MCP (Model Context Protocol) server as a remote HTTP endpoint. Point your AI tool at one URL and OAuth handles the rest — no binary to install, no env vars to manage, no npm package to pin.

Zero-install setup

Drop this into your AI tool's MCP config and you're done:

{
  "mcpServers": {
    "checkupstream": {
      "url": "https://checkupstream.com/api/mcp/transport",
      "transport": "http"
    }
  }
}

Paths:

• Claude Desktop (macOS) — ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Code — project-level .mcp.json or user-level ~/.claude/mcp.json
• Cursor — Settings → MCP → Add new MCP server → paste the URL

The first time Claude or Cursor calls a CheckUpstream tool, it opens your browser to the CheckUpstream consent screen. Approve the request and the AI tool caches a short-lived bearer that it refreshes on its own. Nothing is stored on disk in plain text.

What you get

CheckUpstream's MCP server exposes three kinds of building blocks, and they're designed to be composed:

• Tools — atomic operations the LLM calls to fetch data or perform an action (check_service, diagnose_error, acknowledge_incident). Reads are safe to auto-approve; writes are scope-gated.
• Prompts — pre-built multi-step workflow templates that tell the LLM which tools to chain and how to interpret the results (debug_upstream_error chains diagnose_error → get_blast_radius → get_service_history). Invoke them from your AI tool's prompt picker.
• Resources — URI-addressable entities (checkupstream://services/slug/stripe) the LLM can fetch directly or drill into from a tool result. Auto-complete against your org's actual services, projects, and incidents.

Tool vs. prompt. diagnose_error is a tool — it returns a verdict for one error message. debug_upstream_error is a prompt — it tells the LLM to call diagnose_error, reason about the result, then chain follow-up tools depending on the verdict. Use tools when you know exactly what you want; use prompts when you want the LLM to run a playbook.

Auto-generated from live introspection on 2026-04-13. 81 tools, 4 prompts, 4 resource templates. Run pnpm run inventory:mcp to refresh.

Read tools (60)

Scope: read. Auto-approvable by most clients.

Write tools (15)

Scope: write. Destructive ones accept dry_run: true for a preview.

Prompts (4)

Invoked from the MCP client's prompt picker, not callable as tools.

Resources (4)

URI-addressable. Fetch via ReadMcpResourceTool or your client's equivalent.

Managing connected tools

Connected AI tools show up in Settings → Credentials → AI Connections. Each entry displays the client name, issued date, and last-used timestamp. Revoking an entry invalidates the OAuth grant immediately — the next tool call from that client fails until the user reconnects.

Verify it works

After OAuth completes you land on a confirmation page that auto-bounces you back to your AI tool. Once it does, run one prompt to prove the connection round-trips end to end:

• "Ping CheckUpstream and tell me what my org looks like."

The AI client will call ping_mcp (zero-side-effect liveness probe) followed by whoami (org name + scopes + your most-used tools over the last 30 days). If you see your org name + scope set come back, you're set up.

Example prompts

Once connected, ask your AI assistant questions like:

• "Is Stripe having any issues right now?"
• "Audit my dependencies and tell me what's at risk."
• "Which of my projects use the openai package?"
• "Has Stripe had any incidents in the last 24 hours?"
• "I'm getting a 503 from api.stripe.com — is there a known outage?"
• "Show me the SLA compliance scorecard."
• "Which services have the highest risk scores?"
• "What's the weekly reliability review look like?"
• "Triage incident `inc_abc123`."

Self-hosted CheckUpstream

If you run your own CheckUpstream instance, point your MCP client at its transport URL instead:

{
  "mcpServers": {
    "checkupstream": {
      "url": "https://your-instance.example.com/api/mcp/transport",
      "transport": "http"
    }
  }
}

OAuth discovery (/.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource) is served by the same process — no extra configuration required.

Troubleshooting

Start here: 30-second diagnosis

Most issues fall into one of two buckets. A single command tells you which:

claude mcp list

• checkupstream isn't in the output — the server was never added. Run the install command from Zero-install setup (opens in new tab) above.
• ! Needs authentication — the OAuth flow hasn't completed. Trigger it by asking your AI anything that would use a CheckUpstream tool; the browser should open to /mcp-authorize.
• ✗ Failed to connect — network / transport problem. Jump to MCP server stuck in "Failed to connect" (opens in new tab) below.
• ✓ Connected but my AI doesn't see the tools — the tool list is cached per-session. Jump to Connected but no tools visible (opens in new tab) below.

If none of those match, the specific-symptom sections below cover the rest.

The recover-from-anything fix

Nine times out of ten, this one recipe unsticks a broken install:

claude mcp remove checkupstream -s user
claude mcp add --transport http --scope user checkupstream https://checkupstream.com/api/mcp/transport

Then fully quit and restart your AI tool. Claude Code and Claude Desktop only register newly-connected MCP tools at session start — a hot reconnect leaves the tool list empty even after OAuth succeeds.

Specific symptoms

OAuth popup doesn't open Check that your AI tool supports the remote MCP transport. Claude Desktop, Claude Code, and Cursor all support it as of 2025-06. For older clients, you may need to upgrade.

Browser shows "Authentication Successful" and your AI tool picks up automatically Expected. Claude Code runs a short-lived loopback listener on http://localhost:<port>/callback while auth is pending — when your browser follows the post-approval redirect, the listener catches the code and state, exchanges the code for a bearer, and transitions the MCP server from Needs authentication to connected. You don't have to paste anything.

Browser shows "This site can't be reached" on localhost:<port> after approving Rare — means the loopback listener exited before your browser followed the redirect (usually because you approved more than a minute after starting the flow). Restart the auth flow from your AI tool. If that keeps happening, make sure nothing on your machine is blocking the ephemeral port range (common culprit: heavy VPN rules or a local firewall).

"Invalid or expired token" The access token aged out (access tokens are 1 hour; refresh tokens are 30 days). Reconnect from your AI tool — it will run the refresh grant automatically, or re-run the full OAuth flow if the refresh token is also gone.

MCP server stuck in "Failed to connect" Click reconnect from the MCP settings panel first. If that doesn't recover, remove and re-add the server:

claude mcp remove checkupstream -s user
claude mcp add --transport http checkupstream https://checkupstream.com/api/mcp/transport -s user

Then fully restart Claude Code so the fresh session re-registers the OAuth helper tools, and retry the first tool call. If this fails repeatedly on a self-hosted instance, verify that https://your-instance.example.com/api/mcp/transport serves a direct 401 when hit without a bearer token — a 3xx redirect means your deployment has a canonical-domain rewrite that is stripping the Authorization header on the hop, and the fix is to make the MCP transport host match the canonical.

Tool not found after connecting Restart your AI tool so it re-fetches the tool list. Some clients cache on startup.

Connected but no tools visible claude mcp list shows ✓ Connected for checkupstream, but your Claude session doesn't expose any mcp__checkupstream__* tools when you ask about them. This happens when the MCP finishes connecting after the session starts — the transport is alive but the tool registry for that session never picked the new server up. The fix is to fully quit (⌘Q / exit) and relaunch so the new session reads the connected tool list from scratch. A hot /mcp reconnect is NOT enough; a session restart is.

Need to share access with your team Each team member runs the OAuth flow from their own machine. Revoke individual grants from Settings → Credentials → AI Connections.

Related

• Credentials & Security — the full credential model explained
• Getting Started — connect your first project