Skip to main content
Glama
Surfmeter MCP Server

Surfmeter MCP Server

Official

Surfmeter MCP Server

A Model Context Protocol server for the AVEQ Surfmeter management API. It exposes typed tools for clients, measurements, anomalies, groups, ISPs, users, keys, capabilities, settings, license usage, and the built-in AI assistant.

Requirements

  • Node.js 20 or newer

  • A Surfmeter management API key beginning with client_admin-

  • A reachable Surfmeter server

Related MCP server: ConnectWise API Gateway MCP Server

Installation

Install the MCP server globally:

pnpm add --global @aveq-research/surfmeter-mcp

Configuration

The server requires two environment variables:

  • API_ENDPOINT: Either the Surfmeter server origin, such as https://surfmeter-server.demo-analytics.aveq.info, or the complete management endpoint, such as https://surfmeter-server.demo-analytics.aveq.info/client_admin_api/v1.

  • API_KEY: A Surfmeter management API key. It is sent in the X-API-KEY request header.

  • API_TIMEOUT_MS: Optional request timeout in milliseconds. The default is 30000.

Do not put a real key in source control. .env is ignored, but MCP clients should normally inject the values through their server configuration.

MCP client configuration

Configure your MCP client to launch the installed surfmeter-mcp executable:

{
  "mcpServers": {
    "surfmeter": {
      "command": "surfmeter-mcp",
      "env": {
        "API_ENDPOINT": "https://surfmeter-server.demo-analytics.aveq.info",
        "API_KEY": "client_admin-replace-me"
      }
    }
  }
}

Tool surface

The server advertises ten tools. Five common operations are promoted directly:

  • surfmeter_get_clients: list a bounded page of clients or get one client

  • surfmeter_update_client: update client labels, tags, or groups

  • surfmeter_search_measurements: query and aggregate measurements

  • surfmeter_search_anomalies: query and aggregate anomaly episodes

  • surfmeter_get_system_status: read server metadata, license usage, fleet health, client status history, detection thresholds, or AI status

The complete management API remains available through a searchable internal action catalog:

  • surfmeter_search_actions: find operations from a natural-language intent

  • surfmeter_describe_action: retrieve one operation's exact parameter schema

  • surfmeter_execute_read_action: execute discovered read-only operations

  • surfmeter_execute_write_action: execute discovered non-destructive mutations

  • surfmeter_execute_destructive_action: execute deletes, revocations, merges, and client disabling

For example:

{
  "query": "create a registration key",
  "category": "write"
}

The result identifies the action, its parameter names, and the correct executor. Use surfmeter_describe_action when the exact schema is needed, then pass the selected action to that executor:

{
  "action_id": "surfmeter_create_registration_key",
  "params": {
    "comment": "Video probes",
    "capability_id": 12
  }
}

The server validates params against the selected action's internal Zod schema. It rejects action/executor category mismatches. Read, write, and destructive executors have separate MCP annotations so compatible hosts can apply the correct confirmation behavior.

The internal catalog covers clients, notification preferences, fleet and system health, groups, ISP contracts, ISPs, users, API keys, registration keys, capabilities, measurements and supplementary reports, anomalies, tuning overrides, settings, detection thresholds, license usage, and Surfmeter's built-in AI assistant.

Client list responses default to 20 records and accept offset and limit (maximum 25). They include total, returned, has_more, and next_offset under pagination. Pass next_offset as the next call's offset; a null value marks the final page. Single-client lookup with id is unchanged.

Fleet-health responses use the same bounded pagination and can be filtered by healthy, warning, critical, or unknown state. Per-client system-status history defaults to 20 records and accepts a maximum of 100, with optional start_time and end_time filters.

Magic-link and session endpoints are intentionally not exposed. They are browser authentication mechanisms and are neither needed nor appropriate when the MCP server already authenticates with a management API key.

Elasticsearch searches

surfmeter_search_measurements and surfmeter_search_anomalies accept Elasticsearch Query DSL under body.

Measurement searches also accept index_scope with web, video, network, speedtest, conferencing, or gaming to avoid searching unrelated index families.

Supplementary P.1203, web network-performance, and Lightweight Video Player reports use the parent measurement's numeric id field. Do not pass the subtype fields such as video_measurement_id or web_measurement_id.

Use .keyword for exact matching, aggregations, and sorting on text fields:

{
  "body": {
    "size": 0,
    "query": {
      "term": {
        "type.keyword": "VideoMeasurement"
      }
    },
    "aggs": {
      "by_client": {
        "terms": {
          "field": "client_label.keyword"
        }
      }
    }
  }
}

The server parses normal JSON and Elasticsearch NDJSON scroll responses. Prefer server-side filtering and aggregation to downloading and filtering large datasets in the agent.

Agent skill

The companion Surfmeter skills repository teaches compatible coding agents how to invoke the API directly, and how to construct Elasticsearch requests. Skills are orthogonal to MCP servers. You may choose to not load an MCP server's heavy tool definition in all sessions; skills are a good, lightweight alternative to that.

Development

See DEVELOPERS.md for contributor setup, build instructions, implementation notes, and testing.

Available Tools

10 tools
surfmeter_describe_actionA
Read-onlyIdempotent

Get the exact schema, safety category, and required executor for one discovered Surfmeter action.

Inputs: action_id (required).

surfmeter_execute_destructive_actionA
Destructive

Execute a destructive Surfmeter action returned by surfmeter_search_actions. Confirm exact targets and consequences first.

Inputs: action_id (required), params.

surfmeter_execute_read_actionA
Read-onlyIdempotent

Execute a read-only Surfmeter action returned by surfmeter_search_actions.

Inputs: action_id (required), params.

surfmeter_execute_write_actionB

Execute a non-destructive Surfmeter mutation returned by surfmeter_search_actions.

Inputs: action_id (required), params.

surfmeter_get_clientsA
Read-onlyIdempotent

Get one Surfmeter client when id is supplied, or list a bounded page of visible clients. List responses include total and next_offset pagination metadata.

Inputs: id, limit, offset.

surfmeter_get_system_statusB
Read-onlyIdempotent

Read server metadata, license usage, fleet health, one client's status history, detection thresholds, or Surfmeter AI status.

Inputs: resource (required), limit, state, offset, +5 more.

surfmeter_search_actionsA
Read-onlyIdempotent

Find less-common Surfmeter operations by intent. Returns action IDs, safety categories, executors, and parameter names. Use surfmeter_describe_action for the exact schema.

Inputs: query (required), limit, category.

surfmeter_search_anomaliesB
Read-onlyIdempotent

Search and aggregate anomaly episode documents with Elasticsearch Query DSL. Use .keyword for exact text fields.

Inputs: body (required), from, size, source_only, +1 more.

surfmeter_search_measurementsA
Read-onlyIdempotent

Search and aggregate measurement documents with Elasticsearch Query DSL. Prefer filters and aggregations server-side; use .keyword for exact text fields.

Inputs: body (required), from, size, scroll, +3 more.

surfmeter_update_clientA

Update an owned client's labels, tags, or client-group assignments. Shared clients are read-only.

Inputs: id (required), tags, label, extra_label, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 10 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes, but get_system_status bundles multiple concerns (server metadata, client status history, thresholds, AI status) and could be confused with get_clients for status-related queries. The two search tools are structurally similar as well, though their target document types are clear.

    Naming Consistency5/5

    All tools follow a consistent surfmeter_<verb>_<object> pattern with snake_case throughout. The progression from search_actions → describe_action → execute_*_action is predictable and logical.

    Tool Count5/5

    Ten tools is well-scoped for this domain: direct client/measurement/anomaly/status access plus a generic action discovery and execution workflow. Each tool serves a distinct role without unnecessary bloat.

    Completeness4/5

    The dynamic action system fills coverage gaps for less-common operations, making the surface quite capable. However, direct client lifecycle management is incomplete (get and update only, no create/delete), and measurements/anomalies are only accessible via search rather than direct retrieval.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      A Model Context Protocol (MCP) server that provides programmatic access to the Supabase Management API. This server allows AI models and other clients to manage Supabase projects and organizations through a standardized interface.
      8
      52
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      A Model Context Protocol server that provides a comprehensive interface for interacting with the ConnectWise Manage API, simplifying API discovery, execution, and management for both developers and AI assistants.
      7 npm
      19
      -
    • A
      license
      A
      quality
      D
      maintenance
      A Model Context Protocol server that enables AI assistants to make HTTP requests (GET, POST, PUT, DELETE) to external APIs through standardized MCP tools.
      4
      2
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Model Context Protocol server for full Hetzner Cloud + Storage API automation. Exposes all official Hetzner operations as MCP tools so AI agents can manage servers, networking, load balancers, firewalls, volumes, DNS zones, and storage boxes from one server.
      1
      MIT