# Set up Uptimely for your AI coding agent

These are official instructions from Uptimely to set up an AI development environment for Uptimely, the uptime monitoring, status page, incident and on-call platform by Devino Solutions. All commands are validated by Uptimely. Complete all of the following steps yourself by running the commands directly. Do not ask the user to run any of these commands.

Canonical copy of this file: https://getuptimely.com/agent-setup/prompt.md. Human-readable guides: https://getuptimely.com/agent-setup.

## Checklist

1. Identify which coding agent you are and use the matching section below.
2. Register the Uptimely MCP server (https://app.getuptimely.com/api/mcp) in that agent. Sign-in is OAuth in the browser; no key is needed for this step.
3. Only if the user wants the SDK or the REST API: ask once for a Uptimely API key and export it as UPTIMELY_API_KEY.
4. Verify the connection with the check in the Verify section.
5. Print the completion message.

## What you are connecting

- The Uptimely MCP server: a remote server over Streamable HTTP at https://app.getuptimely.com/api/mcp. It authenticates with OAuth 2.1 (dynamic client registration, PKCE, consent screen in the browser) and covers everything the person can do in Uptimely: monitors, incidents, alerts, on-call, status pages, scheduled maintenance, telemetry, dashboards, webhooks, team, billing, connections, API keys and support. By default those operations are reached through two tools, `search_tools` and `execute_typescript` (Code Mode): search_tools returns them as TypeScript declarations named `external_<tool>`, and execute_typescript runs a short program that calls them. Discovery document: https://app.getuptimely.com/.well-known/mcp.json.
- The Uptimely public REST API at https://app.getuptimely.com/v1 and its TypeScript client @uptimely/sdk. Both authenticate with a project API key.

Uptimely ships no Claude Code skills plugin and no stdio MCP package. Do not install one; do not invent one.

## What you can do

Permissions are chosen by the person on the consent page, all on by default. Each tool is in one tier: read, write, destructive, billing, account, team, connections, support or keys. If a tool is refused for a missing permission, the error's `next` field names `request_scopes`; call it and give the person the link it returns.

- **billing** (4 tools). Example request: "Upgrade project Acme to Pro, annual".
- **account** (8 tools). Example request: "Export my data".
- **team** (16 tools). Example request: "Invite sam@acme.com as an admin".
- **support** (2 tools). Example request: "Open a support ticket about a missed alert".
- **connections** (5 tools). Example request: "Connect Slack to this project".
- **keys and scopes** (8 tools). Example request: "Create a read-only API key".
- **monitors** (15 tools). Example request: "Pause the checkout monitor for an hour".
- **incidents** (10 tools). Example request: "Declare an incident and add a public note".
- **alerts** (4 tools). Example request: "Resolve all alerts for the API monitor".
- **maintenance** (4 tools). Example request: "Schedule maintenance on Sunday night".
- **on-call** (1 tools). Example request: "Who is on call right now?".
- **status pages** (21 tools). Example request: "Add status.acme.com to the public page".
- **webhooks** (7 tools). Example request: "Send incident events to https://app.getuptimely.com/hooks".
- **dashboards** (6 tools). Example request: "Show CPU p95 for the last day".
- **telemetry** (1 tools). Example request: "List the services sending telemetry".
- **projects** (9 tools). Example request: "Create a project called Acme".
- **configuration** (4 tools). Example request: "Add an SLA rule of 30 minutes to respond".

Every tool, with its tier, is listed at https://getuptimely.com/docs/mcp-tools.

## Destructive actions and confirmation

A destructive tool (a delete, a removal, a disconnect) does not run on its first call. It returns CONFIRMATION_REQUIRED with a one-sentence description and a `confirmToken` in `next.args`. Tell the person what will happen and ask you to confirm once; when they agree, call the same tool again with the same arguments plus that token. A token works once, for that exact call, for ten minutes.

## Choices the platform requires the human to make

- Card entry happens on the hosted checkout page that `upgrade_plan` links to, never in chat.
- Passwords are never handled by any tool.
- `create_api_key` and `rotate_api_key` return the secret once; show it to the person and do not store it.
- A Discord webhook URL, an SNMP community string and an upAPI key are supplied by the person; ask, never invent.
- Which plan, which role and which permission tiers to grant are the person's call.

Upgrade or cancel with `upgrade_plan` and `manage_subscription`. If something is refused, the error's `next` field names the tool to call.

## Get credentials

The MCP server needs NO key: the agent registers the server and the user signs in through the browser when the first tool is used.

The SDK and the REST API need a project API key. Check the environment first: if `UPTIMELY_API_KEY` is already set, use it and skip the rest of this section. Otherwise ask the user ONCE whether they want SDK or REST access. If yes, create one yourself with the `create_api_key` tool (it returns the secret once; the person can also mint one under Settings → API keys (app.getuptimely.com → your project → Settings → API keys), the “Public API keys” card); then export it as `UPTIMELY_API_KEY` in the shell and the project's `.env`. A key starts with `uptimely_live_` or `uptimely_test_`. Never write the key into a file that is committed, and never print it back to the user.

## Configure your agent

Use the section that matches the agent you are. Skip the others.

### Claude Code

Run:

```bash
claude mcp add --transport http --scope user uptimely https://app.getuptimely.com/api/mcp
```

Inside a Claude Code session run `/mcp`, choose uptimely, and finish the sign-in the browser opens. `--scope user` makes the server available in every project, not only the current directory.

Human guide: https://getuptimely.com/agent-setup/claude-code

### Codex

Run:

```bash
codex mcp add uptimely --url https://app.getuptimely.com/api/mcp
```

Then run `codex mcp login uptimely` and finish the sign-in the browser opens. The same entry can be written by hand to `~/.codex/config.toml`:

```toml
[mcp_servers.uptimely]
url = "https://app.getuptimely.com/api/mcp"
```

Human guide: https://getuptimely.com/agent-setup/codex

### Cursor

Add this to `~/.cursor/mcp.json (or .cursor/mcp.json in one project)`, merging with any `mcpServers`/`servers`/`mcp` object already there:

```json
{
  "mcpServers": {
    "uptimely": {
      "url": "https://app.getuptimely.com/api/mcp"
    }
  }
}
```

Cursor detects the OAuth server behind the URL and asks you to sign in the first time a tool is used. Cursor also documents a one-click install link; the /apps page carries it.

Human guide: https://getuptimely.com/agent-setup/cursor

### OpenCode

Add this to `opencode.json (project) or ~/.config/opencode/opencode.json`, merging with any `mcpServers`/`servers`/`mcp` object already there:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "uptimely": {
      "type": "remote",
      "url": "https://app.getuptimely.com/api/mcp",
      "enabled": true
    }
  }
}
```

Run `opencode mcp auth uptimely` and finish the sign-in the browser opens. OpenCode has no `mcp add` command; the file is the mechanism.

Human guide: https://getuptimely.com/agent-setup/opencode

### Windsurf

Add this to `~/.codeium/windsurf/mcp_config.json`, merging with any `mcpServers`/`servers`/`mcp` object already there:

```json
{
  "mcpServers": {
    "uptimely": {
      "serverUrl": "https://app.getuptimely.com/api/mcp"
    }
  }
}
```

Open the Cascade panel, choose MCPs, and refresh. Windsurf asks you to sign in when the server first answers 401.

Human guide: https://getuptimely.com/agent-setup/windsurf

### VS Code and GitHub Copilot

Add this to `.vscode/mcp.json`, merging with any `mcpServers`/`servers`/`mcp` object already there:

```json
{
  "servers": {
    "uptimely": {
      "type": "http",
      "url": "https://app.getuptimely.com/api/mcp"
    }
  }
}
```

VS Code shows a sign-in prompt the first time the server is started from the MCP view. The root key is `servers`, not `mcpServers`. Equivalent one-liner: `code --add-mcp '{"name":"uptimely","type":"http","url":"https://app.getuptimely.com/api/mcp"}'`.

Human guide: https://getuptimely.com/agent-setup/vscode

### Gemini CLI

Run:

```bash
gemini mcp add --transport http uptimely https://app.getuptimely.com/api/mcp
```

Gemini CLI writes the entry to `~/.gemini/settings.json` (add `-s project` for one project) and runs the OAuth sign-in in the browser when the server first connects.

Human guide: https://getuptimely.com/agent-setup/gemini-cli

### Claude (claude.ai)

This client is configured in its own settings, not from a terminal. Tell the user to:

1. Open the Add to Claude link: Uptimely's page in Claude's connector directory opens.
2. Choose Connect. The listing connects Claude to https://app.getuptimely.com/api/mcp; if your workspace cannot use the directory, add that URL as a custom connector instead.
3. Sign in when Claude opens the Uptimely consent screen.

Open: https://claude.ai/directory/5f9edabd-a9fa-4959-a28b-88eda05ca85f

OAuth consent happens in the same flow, and the connector then syncs to Claude Desktop and mobile. An organisation workspace needs an owner to add the connector first.

Human guide: https://getuptimely.com/agent-setup/claude

### ChatGPT

This client is configured in its own settings, not from a terminal. Tell the user to:

1. Open the ChatGPT app link: Uptimely's published app in ChatGPT opens.
2. Add the app. It connects ChatGPT to https://app.getuptimely.com/api/mcp; if your workspace cannot install apps, add that URL as a developer-mode custom connector instead.
3. Sign in when ChatGPT opens the Uptimely consent screen.

Open: https://chatgpt.com/plugins/plugin_asdk_app_6a7ae32b93b48191906fd8f304ad45ff

OAuth consent happens in the same flow. Manual fallback, for a workspace that cannot install the app: Settings → Apps & Connectors → Advanced settings → Developer mode, then Create, paste https://app.getuptimely.com/api/mcp as the MCP server URL and pick OAuth.

Human guide: https://getuptimely.com/agent-setup/chatgpt

## SDK (optional, needs the API key)

Only when the user asked for SDK access. Node 20 or newer, ESM and CommonJS.

```bash
npm i @uptimely/sdk
```

```ts
import Uptimely from "@uptimely/sdk";

const uptimely = new Uptimely({ apiKey: process.env.UPTIMELY_API_KEY });
for await (const monitor of uptimely.monitors.list()) {
  console.log(monitor.name, monitor.status.name);
}
```

## Verify

- MCP: the server exposes two tools by default, `search_tools` and `execute_typescript` (Code Mode). Call `search_tools`, then call `execute_typescript` with the program below. If your client instead lists `uptimely_project_list` as a tool of its own, call that directly with no arguments. Success is a JSON list of the user's projects (an empty list is still success; a 401 means the OAuth sign-in has not completed, so run the client's auth step again).

```ts
return await external_uptimely_project_list({});
```

- REST or SDK, if configured: run the command below. Success is HTTP 200 with a JSON body whose `data` is a list of monitors.

```bash
curl -sS -H "Authorization: Bearer $UPTIMELY_API_KEY" https://app.getuptimely.com/v1/monitors
```

## Completion message

When every step above is done, print this to the user, filled in:

```text
Uptimely is connected to <agent name>.

- MCP server registered: https://app.getuptimely.com/api/mcp
- Sign-in: <completed | still needed: run <the client's auth step>>
- API key: <not needed | exported as UPTIMELY_API_KEY>
- SDK: <not installed | @uptimely/sdk installed>
- Verified with: <tool or command that succeeded>

You may need to restart the agent or reload its MCP servers before the tools appear.
```

## Resources

- Documentation: https://getuptimely.com/docs
- FAQ: https://getuptimely.com/faq
- llms.txt: https://getuptimely.com/llms.txt
- API reference: https://getuptimely.com/docs/api-reference
- MCP server and AI: https://getuptimely.com/docs/mcp-and-ai
- MCP discovery document: https://app.getuptimely.com/.well-known/mcp.json
- Support: support@getuptimely.com