MCP monitor configuration reference

Availability

MCP monitors are available on paid plans. Contact support to enable them for your account.

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.