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

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 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 version, measurement options, license usage, 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, groups, ISP contracts, ISPs, users, API keys, registration keys, capabilities, measurements, anomalies, tuning overrides, settings, license usage, and Surfmeter's built-in AI assistant.

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.

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.