MCP monitor configuration reference
MCP monitors are available in organization projects. In other projects, the Monitors page has no Add MCP Monitor button; contact support to turn MCP monitors on.
This page lists the fields of an MCP monitor as the APIContext API and the apimetrics CLI define them. To set up a monitor in the portal, see MCP monitors.
An MCP monitor runs a list of steps against one MCP server URL in one session. The same fields apply to both operations that write a monitor, and every operation is also a CLI command named for its operation ID, such as apimetrics create-mcp-monitor. Run apimetrics create-mcp-monitor --help to print the input schema and an example.
Operations
| Operation | Method and path | Reference |
|---|---|---|
list-mcp-monitors | GET /api/3/monitors/mcp/ | List all MCP Monitors for a project |
create-mcp-monitor | POST /api/3/monitors/mcp/ | Create a new MCP Monitor |
read-mcp-monitor | GET /api/3/monitors/mcp/{monitor_id} | Read an MCP Monitor by ID |
update-mcp-monitor | PUT /api/3/monitors/mcp/{monitor_id} | Update an existing MCP Monitor |
patch-mcp-monitor | PATCH /api/3/monitors/mcp/{monitor_id} | Patch an existing MCP Monitor |
delete-mcp-monitor | DELETE /api/3/monitors/mcp/{monitor_id} | Delete an existing MCP Monitor |
query-mcp-monitor-performance | POST /api/3/monitors/mcp/{monitor_id}/stats/performance | Aggregate performance metrics for an MCP monitor over a window |
query-mcp-performance | POST /api/3/monitors/mcp/stats/performance | Aggregate performance metrics across all MCP monitors in the project |
Every operation accepts an optional apimetrics-project-id header that selects the project.
Monitor fields
These fields go in the request body for create-mcp-monitor and update-mcp-monitor. patch-mcp-monitor takes the same fields, and none of them is required.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
name | string | Yes | none | Display name for the monitor. |
description | string or null | No | none | Optional description for the monitor. |
tags | array of strings | No | none | Tags to apply to the monitor for grouping or advanced features. |
workspace | string | No | global | Workspace to assign the monitor to. |
url | string | Yes | none | Target URL for the monitor. |
overall_timeout_ms | integer | No | 30000 | Session timeout for the monitor, in milliseconds. Accepts 0 to 120000. |
steps | array of steps | No | none | Steps to execute during the MCP session. When you supply the array, it holds at least one step. |
auth_id | string or null | No | none | Auth settings to use with the monitor. |
token_id | string or null | No | none | Auth token to use with the monitor. |
Authentication fields
auth_id and token_id are the only authentication fields in the MCP monitor schema. Each takes the ID of an existing object as a string, or null for none. auth_id selects the auth settings for the monitor and token_id selects the auth token. For how auth settings and tokens work, see Authentication model.
Step fields
Each entry in steps is an object, and step_type selects its type. The schema sets additionalProperties to false on every step type, so a step with a field that is not listed here does not match the schema.
Every step type has these fields:
| Field | Type | Required | Description |
|---|---|---|---|
step_type | string | No | The step type from the table below. Each schema defaults it to its own type. |
timeout_ms | integer | Yes | Step timeout, in milliseconds. Accepts 0 to 120000. |
wait_ms | integer | Yes | Time to wait after finishing the step, in milliseconds. Accepts 0 to 120000. |
Step types
step_type | What it does | Additional fields |
|---|---|---|
list_tools | Lists the tools the server exposes. | None |
call_tool | Calls one tool. | tool_name (string, required): name of the tool to call. parameters (object or null): arguments to provide for the tool call. |
list_resources | Lists the resources the server exposes. | None |
list_resource_templates | Lists the resource templates the server exposes. | None |
read_resource | Reads one resource. | resource_uri (string, required): URI of the resource to read. |
list_prompts | Lists the prompts the server exposes. | None |
get_prompt | Gets one prompt. | prompt_name (string, required): name of the prompt to get. parameters (object or null): arguments to provide to the prompt template. |
wait | Waits. | None |
Example
This body creates a monitor with two steps, the first listing tools and the second calling one tool with an argument. It is the call_tool example from the API reference, with a placeholder server URL.
{
"name": "Echo health check",
"tags": [],
"workspace": "global",
"url": "https://mcp.example.com",
"overall_timeout_ms": 60000,
"steps": [
{ "step_type": "list_tools", "timeout_ms": 10000, "wait_ms": 0 },
{
"step_type": "call_tool",
"timeout_ms": 15000,
"wait_ms": 0,
"tool_name": "echo",
"parameters": { "message": "ping" }
}
]
}
Monitor object
create-mcp-monitor, read-mcp-monitor, update-mcp-monitor, and patch-mcp-monitor return the monitor as an object with three parts.
| Field | Type | Description |
|---|---|---|
id | string | The monitor ID. |
meta | object | monitor_type (mcp), name, description, tags, domain (the domain of the target URL), created, last_update, owner, and workspace. |
setup | object | url, overall_timeout_ms, steps, auth_id, and token_id. The step objects are the ones described above. |
list-mcp-monitors returns a results array of these objects.
Performance queries
query-mcp-monitor-performance aggregates one monitor's timings over a window, and query-mcp-performance does the same across the project's MCP monitors. Both take this request body.
| Field | Type | Required | Description |
|---|---|---|---|
from | string (date-time) | Yes | Window start, as a UTC ISO timestamp, inclusive. |
to | string (date-time) | Yes | Window end, as a UTC ISO timestamp, exclusive. |
interval | string (ISO 8601 duration) or null | No | Bucket size for time-series grouping, such as PT1H or PT15M. When omitted, the whole window is one bucket. |
metrics | array | No | Metrics to aggregate: total, initialize, dns, tcp, tls, network, total_no_dns. Defaults to the monitor type's standard set. |
measures | array | No | Statistical measures to return for each metric: mean, p50, p90, p95, p99. Defaults to all five. |
group_by | array | No | Dimensions to group results by: location, interval, monitor. |
locations | array of strings | No | Restrict to these location IDs. Empty means all locations. |
status | array | No | Restrict to these result categories: PASS, SLOW, WARNING, FAIL. Empty means all categories. |
poor_thresholds | object | No | A threshold value for each metric, keyed by metric name. When you supply it, the response includes a poor_count for each matching metric, counting samples whose value exceeds the threshold. |
On the project-wide query, group by monitor to get one group per monitor, or by monitor and interval for a time series per monitor. Without a monitor grouping, the result is a single project-wide aggregate.
Next steps
- MCP monitors: set up an MCP monitor in the portal.
- Monitors: what a monitor is and the three monitor types.
- CLI generated commands: how each API operation becomes a command.