# Agent install (/docs/agent)

> Install and configure the ServerMetry monitoring agent on Linux, macOS, and Windows.



The ServerMetry agent is a lightweight Python 3.8+ process with **no third-party dependencies**. It collects CPU, memory, disk, network, and process metrics and posts them to the API (default: once per minute).

> Tip: After you add a server in the dashboard, ServerMetry shows the exact install command with your API key pre-filled.

## Linux / macOS [#linux--macos]

Always download and review install scripts before running them with elevated privileges.

```bash
# 1. Download
curl -fsSL https://raw.githubusercontent.com/FloBaMedia/servermetry-client/main/agent/install.sh -o /tmp/install.sh

# 2. Review
cat /tmp/install.sh

# 3. Install (production API)
chmod +x /tmp/install.sh
SERVERMETRY_URL=https://api.servermetry.com SERVERMETRY_KEY=sp_live_... sudo /tmp/install.sh
```

Interactive install (prompts for URL and key):

```bash
curl -fsSL https://raw.githubusercontent.com/FloBaMedia/servermetry-client/main/agent/install.sh -o /tmp/install.sh
chmod +x /tmp/install.sh
sudo /tmp/install.sh
```

## Windows (PowerShell as Administrator) [#windows-powershell-as-administrator]

```powershell
Invoke-WebRequest -Uri 'https://raw.githubusercontent.com/FloBaMedia/servermetry-client/main/agent/install-windows.ps1' -OutFile $env:TEMP\install-servermetry.ps1
Get-Content $env:TEMP\install-servermetry.ps1
& $env:TEMP\install-servermetry.ps1 -ApiUrl "https://api.servermetry.com" -ApiKey "sp_live_..."
```

Install Python **for all users** so the Scheduled Task running as `SYSTEM` can execute it.

## Install paths [#install-paths]

|             | Linux / macOS                    | Windows                                 |
| ----------- | -------------------------------- | --------------------------------------- |
| Install dir | `/etc/servermetry/`              | `C:\ProgramData\ServerMetry\`           |
| Config      | `/etc/servermetry/agent.conf`    | `C:\ProgramData\ServerMetry\agent.conf` |
| Log         | `/var/log/servermetry-agent.log` | `C:\ProgramData\ServerMetry\agent.log`  |
| Scheduler   | crontab (`* * * * *`)            | Scheduled Task (every 1 min)            |
| Runs as     | root                             | SYSTEM                                  |

## Configuration [#configuration]

Config file:

```ini
[servermetry]
api_url = https://api.servermetry.com
api_key  = sp_live_...
debug    = false
```

Environment variables (override the config file):

| Variable              | Description                  |
| --------------------- | ---------------------------- |
| `SERVERMETRY_API_URL` | API base URL                 |
| `SERVERMETRY_API_KEY` | Server API key               |
| `SERVERMETRY_DEBUG`   | Set to `1` for debug logging |

Legacy `SERVERPULSE_*` names are still accepted.

## Remote configuration [#remote-configuration]

On each run the agent fetches `GET /api/v1/agent/config` and can apply timezone, locale, NTP, DNS, report interval, and auto-update settings from the dashboard **Config** tab.

## Useful CLI flags [#useful-cli-flags]

```bash
python agent.py --dry-run          # print metrics as JSON, no HTTP
python agent.py --debug            # verbose stderr logging
python agent.py --no-apply-config  # skip remote config
```

Source and uninstall scripts: [servermetry-client on GitHub](https://github.com/FloBaMedia/servermetry-client).


# Alerts & notifications (/docs/alerts)

> How ServerMetry alert rules, severities, and notification channels work.



## Alert rules [#alert-rules]

Alert rules evaluate metrics (and related conditions) against thresholds. You can create:

* **Global rules** — apply across the organization
* **Server-specific rules** — override or extend for one host
* **Template rules** — reused when applying a template to servers

Typical fields:

| Field             | Meaning                              |
| ----------------- | ------------------------------------ |
| Metric            | e.g. `cpuUsagePercent`, disk, memory |
| Operator          | GT, LT, …                            |
| Threshold         | Numeric limit                        |
| Severity          | `WARNING` or `CRITICAL`              |
| Evaluation window | How long the condition must hold     |

Manage rules under **Alert Rules** in the dashboard, or via [MCP](/docs/mcp) / the REST API.

## Alert lifecycle [#alert-lifecycle]

1. Condition matches → alert opens
2. Notifications fire on configured channels
3. Condition clears or you resolve the alert → alert closes

Open alerts appear on the dashboard and on the server detail page.

## Notification channels [#notification-channels]

Configure channels under **Notifications** (email, webhooks, and other integrations depending on your plan). Channels can be global or scoped. Test a channel from the UI before relying on it in production.

## Maintenance windows [#maintenance-windows]

During a maintenance window, alerting for the covered servers can be suppressed so planned work does not page the team. Create windows under **Maintenance**.

## Digests [#digests]

Organizations can enable alert digests (frequency configurable in organization settings) for a summarized view instead of only real-time noise.


# API reference (/docs/api)

> Link to the live OpenAPI / Swagger documentation for the ServerMetry API.



ServerMetry publishes a full OpenAPI 3.1 specification. Use the interactive Swagger UI for request/response schemas, or fetch the raw JSON for code generation.

## Live docs [#live-docs]

| Resource     | URL                                                                                  |
| ------------ | ------------------------------------------------------------------------------------ |
| Swagger UI   | [https://api.servermetry.com/docs](https://api.servermetry.com/docs)                 |
| OpenAPI JSON | [https://api.servermetry.com/openapi.json](https://api.servermetry.com/openapi.json) |

Local development (API on port 3601):

* Swagger: `http://localhost:3601/docs`
* Spec: `http://localhost:3601/openapi.json`

## Auth overview [#auth-overview]

* **Session / cookie** — browser dashboard (better-auth)
* **Server agent key** — `sp_live_…` for agent metrics endpoints
* **MCP key** — `sp_mcp_…` Bearer token for the MCP endpoint (see [MCP setup](/docs/mcp))

Exact auth requirements are documented per operation in Swagger.

## Related [#related]

* [Agent install](/docs/agent) — how agents authenticate
* [MCP setup](/docs/mcp) — AI tool access without writing REST clients
* Product docs index: [`/llms.txt`](/llms.txt)


# Getting started (/docs/getting-started)

> Create a ServerMetry account, set up an organization, and add your first server.



## 1. Create an account [#1-create-an-account]

Open [servermetry.com/login](https://servermetry.com/login) and sign in with email OTP or a passkey. There is no password login.

## 2. Create an organization [#2-create-an-organization]

After the first sign-in, onboarding asks you to create an organization. All servers, alerts, and billing belong to that organization.

## 3. Add a server [#3-add-a-server]

In the dashboard:

1. Go to **Servers** → **Add server**
2. Give the server a name (and optional project)
3. Copy the generated install command — it already includes your API URL and server key

## 4. Install the agent [#4-install-the-agent]

Run the install command on the target host. Details for Linux/macOS and Windows are in [Agent install](/docs/agent).

Once the agent reports in, the server status updates in the dashboard (typically within one minute).

## 5. Optional next steps [#5-optional-next-steps]

* Configure [alert rules](/docs/alerts) and notification channels
* Connect [MCP](/docs/mcp) so Cursor or Claude can query your fleet
* Review plan limits under **Billing** if you need more servers


# ServerMetry Docs (/docs)

> Product documentation for ServerMetry — monitoring, agents, alerts, and AI (MCP) integration.



ServerMetry is a server monitoring platform with real-time metrics, intelligent alerting, and AI assistant access via MCP.

## What you can do [#what-you-can-do]

* Monitor CPU, memory, disk, network, and services across your fleet
* Install a lightweight Python agent on Linux, macOS, and Windows
* Get alerts via email, webhooks, and other notification channels
* Manage servers, alerts, and rules from Cursor or Claude using MCP

## Start here [#start-here]

1. [Getting started](/docs/getting-started) — create an account and your first organization
2. [Agent install](/docs/agent) — ship metrics from a server
3. [MCP setup](/docs/mcp) — connect AI tools to ServerMetry
4. [Alerts](/docs/alerts) — rules, severity, and notifications
5. [API reference](/docs/api) — OpenAPI / Swagger

## For AI agents [#for-ai-agents]

This site publishes machine-readable documentation:

| Resource          | URL                                                                                               |
| ----------------- | ------------------------------------------------------------------------------------------------- |
| Docs index        | [`/llms.txt`](/llms.txt)                                                                          |
| Full docs dump    | [`/llms-full.txt`](/llms-full.txt)                                                                |
| Per-page Markdown | append `.md` (index: [`/docs/index.md`](/docs/index.md), e.g. [`/docs/agent.md`](/docs/agent.md)) |

Prefer these endpoints over scraping HTML.


# MCP setup (/docs/mcp)

> Connect Cursor, Claude, and other MCP clients to ServerMetry for AI-assisted monitoring.



ServerMetry exposes an [MCP](https://modelcontextprotocol.io/) endpoint so AI assistants can query servers, alerts, and related resources — and perform selected write actions.

## Endpoint [#endpoint]

| Environment | MCP URL                           |
| ----------- | --------------------------------- |
| Production  | `https://api.servermetry.com/mcp` |
| Local API   | `http://localhost:3601/mcp`       |

Use the **direct API URL** for MCP clients. Do not point Cursor/Claude at the frontend origin.

## Create an MCP key [#create-an-mcp-key]

1. Sign in to the dashboard
2. Open **Settings → MCP Keys** (or API Keys)
3. Create a key — it is shown **once**; store it securely

Keys are organization-scoped (`sp_mcp_…`).

## Cursor [#cursor]

Add to `~/.cursor/mcp.json` or a project `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "servermetry": {
      "url": "https://api.servermetry.com/mcp",
      "headers": {
        "Authorization": "Bearer sp_mcp_YOUR_KEY"
      }
    }
  }
}
```

Reload Cursor so the MCP connection refreshes.

## Claude Desktop / Claude Code [#claude-desktop--claude-code]

Use the same URL and `Authorization: Bearer …` header in the Claude MCP server config (see the dashboard page for a ready-made JSON snippet).

## Example tools [#example-tools]

| Tool                                                           | Purpose                 |
| -------------------------------------------------------------- | ----------------------- |
| `get_dashboard`                                                | Aggregated overview     |
| `list_servers` / `get_server`                                  | Fleet and server detail |
| `list_alerts` / `resolve_alert`                                | Alert triage            |
| `list_alert_rules` / `create_alert_rule` / `delete_alert_rule` | Rule management         |
| `list_notification_channels`                                   | Channels                |
| `list_services` / `create_service` / …                         | Service monitoring      |
| `list_projects` / `create_project` / …                         | Projects                |
| `list_backup_plans` / `create_backup_plan`                     | Backup plans            |
| `list_maintenance_windows` / …                                 | Maintenance             |
| `list_templates`                                               | Templates               |

The full tool list is returned by the MCP `tools/list` handshake.

## Example prompts [#example-prompts]

```
Use ServerMetry MCP: list all servers with status OFFLINE or CRITICAL and summarize what is going on.
```

```
Via ServerMetry MCP: list open CRITICAL alerts, group by server, and suggest which alert rules to review.
```

```
Create a global alert rule via ServerMetry MCP: name "High CPU", metric cpuUsagePercent, operator GT, threshold 90, severity CRITICAL, evaluation window 5 minutes.
```

## Security [#security]

* Never commit MCP keys to git
* Rotate keys regularly (delete + recreate in the dashboard)
* On compromise, delete the key immediately

## Troubleshooting [#troubleshooting]

| Problem            | Fix                                     |
| ------------------ | --------------------------------------- |
| `401 Unauthorized` | Check key and `Bearer ` prefix          |
| No connection      | Use API URL (not frontend), valid HTTPS |
| No tools listed    | Reload MCP panel; verify key org access |
| Empty server list  | Key belongs to a different organization |