> ## Documentation Index > Fetch the complete documentation index at: https://docs.appsignal.com/llms.txt > Use this file to discover all available pages before exploring further. # MCP Tool Reference AppSignal MCP exposes 24 tools across seven areas: **error incidents**, **performance**, **anomaly detection**, **logging**, **metrics**, **dashboards**, and **app discovery**. Tools include both read and write operations. ## Workflows These examples show how tools compose together for common tasks. ### Investigating a production error 1. List recent open exceptions: *"Show me all open incidents in production from the last 24 hours"* 2. Get full details on a specific incident: *"Get the details for incident #847 including the stack trace"* 3. Pull traces to see what happened at the code level: *"Get the error traces for incident #847"* 4. Document your findings: *"Add a note to incident #847: investigated the database timeout — connection pool was exhausted during peak traffic"* 5. Resolve it: *"Close incident #847"* ### Profiling a slow action 1. Get a performance overview: *"Which actions are slowest in the web namespace right now?"* 2. Pull traces for the worst offender: *"Get traces for BlogPostsController#index from the last hour"* 3. Inspect the span tree to find the bottleneck: *"Show me the full span tree for trace abc123"* 4. Drill into a specific span: *"Get the details for span def456 in trace abc123"* ### Triaging a batch of incidents 1. *"Find all open incidents in the background namespace from the last week"* 2. *"Mark incidents #120, #121, and #122 as work in progress and assign them to Jana"* 3. *"Close all incidents related to ActionMailer — they were fixed in the last deploy"* ### Searching logs during an incident 1. *"Find all error logs from the last hour"* 2. *"Show me logs where message contains 'timeout' on web-1 between 14:00 and 15:00"* 3. *"Get fatal logs from the payments source over the last 30 minutes"* ### Reconstructing a customer journey When a user reports something went wrong, the answer is usually scattered across logs from multiple sources, plus errors and traces. Stitching that timeline together by hand is the kind of work the logging UI can't do for you, but an agent can. 1. *"Get all logs for user.id=4321 from production over the last 24 hours, across every source"* 2. *"Narrow that to the window between 14:00 and 15:30 UTC and group the results by source"* 3. *"List any open exception incidents from production in that same window — anything tagged with user.id=4321?"* 4. *"For incident #903, pull the error traces and walk the span tree"* 5. *"Summarize what happened: which actions did this user hit, what failed, and where did the error originate?"* This pulls from `get_log_lines`, `get_exception_incidents`, and `get_traces` in a single conversation. The final summary step is where MCP earns its keep — the agent composes the narrative, not you. ### Setting up log processing AppSignal executes log line actions during ingestion, in the order you define. A common pattern is to emit a metric, create a trigger, then filter — this ensures AppSignal captures the signal before discarding the log line. 1. Check the existing log line actions and their order: use `get_app_resources` with `sections: ["log_line_actions"]` 2. *"Create a metrics action that counts log lines where severity is error as log.error\_count"* 3. *"Add a trigger action that fires an alert when severity is fatal"* 4. *"Add a filter to drop all health check log lines"* 5. *"Reorder those actions so the metrics action runs first, then the trigger, then the filter"* ### Creating an anomaly detection trigger 1. Discover available metrics: *"What metrics are available for my production app?"* 2. Check available tags: *"What tags are available for response\_time?"* 3. Create the trigger: *"Create a trigger that fires when mean response time exceeds 500ms for more than 5 minutes, and notify the Slack #alerts channel"* 4. Archive an old trigger once replaced: use `get_triggers` to find the ID first, then *"Archive the old response\_time trigger"* ### Building a monitoring dashboard 1. *"What metrics are available for my production app?"* 2. *"Create a dashboard called 'API Health' in production"* 3. *"Add a line chart of p95 response time by action to the API Health dashboard"* 4. *"Add an area chart of error rate broken down by namespace"* *** ## Tool reference Every tool takes `app_name` and `app_environment` to identify which application to target. Both are matched case-insensitively, so `MyApp/Production` and `myapp/production` resolve to the same application. ### App discovery #### `get_applications` Get all AppSignal applications the user has access to. Returns applications in `app_name/app_environment` format. Use this first to discover available applications before calling other tools. No parameters required. *** #### `get_app_resources` Discover available resources in an AppSignal application — namespaces, dashboards, users, notifiers, log sources, log line actions, and deploy markers. Particularly useful when setting up triggers, assigning incidents, or understanding the structure of an application. | Parameter | Required | Description | | ----------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `app_name` | yes | Name of the AppSignal application. | | `app_environment` | yes | Environment (e.g. `production`, `staging`). | | `sections` | no | Sections to retrieve: `users`, `notifiers`, `namespaces`, `dashboards`, `log_sources`, `log_line_actions`, `log_views`, `deploy_markers`. Returns all if not specified. | *** ### Error incidents #### `get_exception_incidents` List and search AppSignal exceptions and errors. Use this to get an overview of recent exceptions, search within a time period, find incidents by state, or check which incidents need attention. Returns 50 incidents per page. | Parameter | Required | Description | | ----------------- | -------- | -------------------------------------------------------------------------------------- | | `app_name` | yes | Name of the AppSignal application. | | `app_environment` | yes | Environment. | | `namespaces` | no | Comma-separated list of namespaces to filter by (e.g. `web,background`). | | `start` | no | Start of time range in ISO 8601 format. Defaults to the most recent deploy if omitted. | | `end` | no | End of time range in ISO 8601 format. Required if `start` is provided. | | `states` | no | Comma-separated states: `open`, `closed`, `wip`. Returns all states if not specified. | | `page` | no | Page number (1-based, defaults to 1). | *** #### `get_incident` Get detailed information about an AppSignal incident. Returns current state, assignment, first and last occurrence, error messages, stack traces, or anomaly alert details. Supports exception and anomaly incidents. | Parameter | Required | Description | | ----------------- | -------- | ------------------------------------------------------------------- | | `app_name` | yes | Name of the AppSignal application. | | `app_environment` | yes | Environment. | | `number` | yes | The numeric incident ID shown in AppSignal URLs and incident lists. | *** #### `update_incidents` Bulk update incidents for an AppSignal application. Use this to change incident state, update severity, or assign and unassign team members across multiple incidents at once. Use `get_app_resources` with `sections: ["users"]` to find user IDs for assignment. | Parameter | Required | Description | | ----------------- | -------- | ------------------------------------------------------------------- | | `app_name` | yes | Name of the AppSignal application. | | `app_environment` | yes | Environment. | | `incidents` | no | List of incident numbers to update (e.g. `[123, 456, 789]`). | | `state` | no | `open`, `closed`, or `wip` (work in progress). | | `severity` | no | `critical`, `high`, `low`, `none`, `informational`, or `untriaged`. | | `assign_users` | no | List of user IDs to assign as handlers. | | `unassign_users` | no | List of user IDs to remove from the incident. | *** #### `create_incident_note` Create a note on an AppSignal incident. Markdown is supported. Use this to add comments, status updates, investigation findings, or resolution steps. | Parameter | Required | Description | | ----------------- | -------- | ----------------------------------------------- | | `app_name` | yes | Name of the AppSignal application. | | `app_environment` | yes | Environment. | | `number` | yes | The numeric incident ID. | | `content` | yes | Note content. Markdown formatting is supported. | *** ### Performance #### `get_performance` Performance overview: sample-based performance incidents and slow actions from traces. For standard Ruby and Elixir apps, returns sample-based performance incidents. For apps that also send OpenTelemetry traces, additionally returns a ranked list of actions with mean duration, throughput, and error rate. Apps being migrated to OpenTelemetry may return both. Follow-up tools: use `get_incident` to inspect a specific performance incident, `get_traces` to pull sample traces for a slow action, and `update_incidents` to change state, severity, or assignees. | Parameter | Required | Description | | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `app_name` | yes | Name of the AppSignal application. | | `app_environment` | yes | Environment. | | `namespaces` | no | Comma-separated namespaces. Applies to both performance incidents and OpenTelemetry actions. | | `start` | no | Start of time range in ISO 8601 format. Defaults to the most recent deploy for sample-based incidents, or 24 hours ago for OpenTelemetry actions. | | `end` | no | End of time range in ISO 8601 format. Required if `start` is provided. | | `states` | no | Comma-separated states: `open`, `closed`, `wip`. Applies to sample-based incidents only. | | `revision` | no | Scope to a specific deploy. Use `"last"` for the most recent deploy, or pass a revision hash. Ignored when `start`/`end` is provided. Use `get_app_resources(sections: ["deploy_markers"])` to list available revisions. | | `page` | no | Page number for sample-based incidents (1-based, defaults to 1). OpenTelemetry actions are returned as a complete ranked list. | *** #### `get_traces` Query performance and error traces, inspect span trees, and view span details. Supports two trace types: * **Performance traces** — identified by namespace and `action_name`. Use these to investigate slow requests. * **Error traces** — identified by digest. Get the digest from `get_incident` or `get_exception_incidents`, then use it here to see the actual error traces. Each trace type supports three modes: 1. **List mode** — find traces and get trace IDs. Provide namespace + `action_name`, or `digest`. 2. **Tree mode** — pass a `trace_id` to see all spans as a compact tree. 3. **Span detail mode** — pass `trace_id` and `span_id` for full span attributes, events, and resource info. The typical workflow is: list traces → inspect a trace tree → drill into a span. | Parameter | Required | Description | | ----------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------ | | `app_name` | yes | Name of the AppSignal application. | | `app_environment` | yes | Environment. | | `namespace` | yes (performance) | The namespace to search in (e.g. `web`, `background`). Not needed for error traces. | | `action_name` | yes (performance) | The action name (e.g. `BlogPostsController#index`). Not needed for error traces. | | `digest` | yes (error) | The exception incident digest. Switches to error trace mode. Cannot be combined with `namespace` or `action_name`. | | `trace_id` | no | Switches to tree mode. Returns all spans for this trace. | | `span_id` | no | Switches to span detail mode. Requires `trace_id`. | | `start` | no | Start of time range in ISO 8601 format. Defaults to 24 hours ago. Performance traces only. | | `end` | no | End of time range in ISO 8601 format. Defaults to now. Performance traces only. | | `min_duration_ms` | no | Filter to traces slower than this threshold in milliseconds. List mode only. | | `limit` | no | Maximum number of traces to return (1–100, default 25). List mode only. | *** ### Anomaly detection #### `get_anomaly_incidents` List and search AppSignal anomaly detection alerts. Returns 50 alerts per page, including timestamps and values for each alert. | Parameter | Required | Description | | ----------------- | -------- | ------------------------------------------------------------------------------------------- | | `app_name` | yes | Name of the AppSignal application. | | `app_environment` | yes | Environment. | | `state` | no | `open`, `closed`, `warmup`, `cooldown`, or `archived`. Returns all states if not specified. | | `trigger_id` | no | Filter to incidents from a specific trigger. Use `get_triggers` to find trigger IDs. | | `page` | no | Page number (1-based, defaults to 1). | *** #### `get_triggers` List anomaly detection triggers for an AppSignal application. Returns active (non-archived) triggers with their complete configuration — conditions, notifiers, and dashboard links. Use this to find trigger IDs before calling `manage_trigger` or `archive_trigger`. | Parameter | Required | Description | | ----------------- | -------- | --------------------------------------------------------------- | | `app_name` | yes | Name of the AppSignal application. | | `app_environment` | yes | Environment. | | `metric_name` | no | Filter by metric name (e.g. `response_time`, `error_rate`). | | `kind` | no | Filter by trigger kind. | | `tags` | no | Filter by tags, e.g. `[{"key": "hostname", "value": "web-1"}]`. | | `page` | no | Page number (1-based, defaults to 1). | *** #### `manage_trigger` Create or update an anomaly detection trigger. Triggers are immutable. When you update a trigger, AppSignal archives the existing one (closing all its alerts and incidents) and creates a new one with a version chain reference. Provide all fields for both create and update operations. Use `get_metric_names` and `get_metric_tags` to discover available metrics and fields. Use `get_app_resources(sections: ["notifiers"])` to find notifier IDs. | Parameter | Required | Description | | --------------------- | -------- | ------------------------------------------------------------------------------------------------- | | `app_name` | yes | Name of the AppSignal application. | | `app_environment` | yes | Environment. | | `metric_name` | yes | The metric this trigger monitors. | | `kind` | yes | Trigger kind. Use `"Advanced"` for custom metrics. | | `field` | yes | Metric field to compare: `gauge`, `mean`, `p90`, `p95`, `counter`, or `count`. | | `condition_value` | yes | Threshold value (e.g. `500.0` for "response time > 500ms"). | | `comparison_operator` | yes | `<`, `>`, `<=`, `>=`, `==`, or `!=`. | | `warmup_duration` | yes | Minutes the condition must be met before an alert opens. Use `0` for immediate. | | `cooldown_duration` | yes | Minutes the condition must no longer be met before an alert closes. | | `id` | no | ID of an existing trigger to update. If provided, archives the old trigger and creates a new one. | | `notifier_ids` | no | Notifier IDs to send alerts to. | | `tags` | no | Tag filters to scope which metrics are included. Supports wildcards (`*`). | | `name` | no | Display name. Defaults to the metric name if not provided. | | `description` | no | Description of what this trigger monitors and what to do when it fires. | | `dashboard_id` | no | Dashboard ID to link in notifications. | | `no_match_is_zero` | no | If true, treat missing metric data as 0. Useful for counters that may not report when idle. | | `format` | no | Data format of the metric (e.g. `duration`, `size`, `percent`). | *** #### `archive_trigger` Archive an anomaly detection trigger and close all associated alerts and incidents. Idempotent — no-ops if the trigger is already archived. Use `get_triggers` to find the trigger ID. | Parameter | Required | Description | | ----------------- | -------- | ---------------------------------- | | `app_name` | yes | Name of the AppSignal application. | | `app_environment` | yes | Environment. | | `id` | yes | ID of the trigger to archive. | *** ### Logging #### `get_log_lines` Query log lines using AppSignal's expression syntax. Supports exact match, contains, negation, numeric comparisons, boolean logic, and nested attributes. Returns up to 100 lines per call, newest-first by default. For large time ranges, split into multiple calls and iterate forward. **Query syntax:** | Pattern | Example | | ------------------ | ------------------------------------------------------- | | Exact match | `severity=error` | | Contains | `message:timeout` | | Does not contain | `message!:debug` | | Not equal | `hostname!=web-1` | | Numeric comparison | `duration>100` | | Boolean logic | `severity=error AND (hostname=web-1 OR hostname=web-2)` | | Quoted values | `group="background jobs"` | | Nested attributes | `user.id=123` | Available fields: `severity`, `hostname`, `group`, `message`, and any custom attributes. | Parameter | Required | Description | | ----------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `app_name` | yes | Name of the AppSignal application. | | `app_environment` | yes | Environment. | | `query` | yes | Expression query. Use an empty string to retrieve all logs. | | `source_ids` | no | IDs of log sources to query. Queries all sources if not specified. Use `get_app_resources(sections: ["log_sources"])` to find source IDs. | | `start` | no | Start of time range in ISO 8601 format. Defaults to one query window ago. | | `end` | no | End of time range in ISO 8601 format. Defaults to now. | | `limit` | no | Number of log lines to return (1–100, default 50). | | `order` | no | `desc` (newest first, default) or `asc` (oldest first). | *** #### `manage_log_line_action` Create or update a log line action. Log line actions run during log ingestion, in the order you define. There are three types: * **filter** — discards matching log lines so they are never stored or processed further * **trigger** — fires alerts and incidents when the query matches * **metrics** — extracts counter, gauge, or distribution metrics from matching log lines Execution order matters: if a filter discards a log line, subsequent actions never see it. A common pattern is to place metric and trigger actions before any filter actions. Use `reorder_log_line_actions` to change the order after creation. New actions are appended at the end of the execution order. | Parameter | Required | Description | | ------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `app_name` | yes | Name of the AppSignal application. | | `app_environment` | yes | Environment. | | `name` | yes (create) | Name of the action (e.g. `"Drop health checks"`, `"Track error count"`). | | `query` | yes (create) | Query expression to match against log lines. | | `action_type` | yes (create) | `filter`, `trigger`, or `metrics`. Cannot be changed on update. | | `id` | no | ID of an existing action to update. If omitted, creates a new action. | | `source_ids` | no | Log source IDs this action applies to. Applies to all sources if not specified. | | `log_line_metrics` | no | Metric definitions to extract. Required when creating a `metrics` action. Each metric requires `name` and `metric_type` (`counter`, `gauge`, or `distribution`). `gauge` and `distribution` also require a `field` to extract the value from. When updating, replaces all existing metric definitions. | *** #### `reorder_log_line_actions` Change the execution order of log line actions. Provide action IDs in the desired sequence. Any action IDs not included are appended at the end in their current relative order. Use `get_app_resources(sections: ["log_line_actions"])` to find IDs and see the current order. | Parameter | Required | Description | | ----------------- | -------- | ------------------------------------------------------------------------------------------------- | | `app_name` | yes | Name of the AppSignal application. | | `app_environment` | yes | Environment. | | `action_ids` | yes | Ordered list of log line action IDs. The first ID in the list is executed first during ingestion. | *** #### `delete_log_line_action` Permanently delete a log line action. Use `get_app_resources(sections: ["log_line_actions"])` to find the action ID first. | Parameter | Required | Description | | ----------------- | -------- | ------------------------------------ | | `app_name` | yes | Name of the AppSignal application. | | `app_environment` | yes | Environment. | | `id` | yes | ID of the log line action to delete. | *** ### Metrics #### `discover_metrics` Discover available metric categories and their metrics for monitoring. Use this to get an overview of what you can monitor, or drill into a specific category. Also accepts a `dashboard:id` reference to show metrics used in a specific dashboard. | Parameter | Required | Description | | ----------------- | -------- | ------------------------------------------------------------------------------------------------ | | `app_name` | yes | Name of the AppSignal application. | | `app_environment` | yes | Environment. | | `metric_subject` | no | Metric category name (e.g. `performance_metrics`, `host_metrics`) or a `dashboard:id` reference. | *** #### `get_metric_names` Get the names of all metrics for the given application. Returns metric names as a comma-separated string. Use these as input to `get_metric_tags`, `get_metrics_timeseries`, and `get_metrics_list`. | Parameter | Required | Description | | ----------------- | -------- | ---------------------------------- | | `app_name` | yes | Name of the AppSignal application. | | `app_environment` | yes | Environment. | *** #### `get_metric_tags` Get the tags and metric type (Gauge, Counter, etc.) for a specific metric. Use the results to build valid queries with `get_metrics_timeseries` and `get_metrics_list`. | Parameter | Required | Description | | ----------------- | -------- | --------------------------------------------------------------------- | | `app_name` | yes | Name of the AppSignal application. | | `app_environment` | yes | Environment. | | `metric_name` | yes | Name of the metric. Use `get_metric_names` to find available metrics. | *** #### `get_metrics_timeseries` Get a timeseries for a metric in the given application. Returns point-by-point data for a given time range, metric type, and tag combination. Tag values support wildcard matching with `*`. | Parameter | Required | Description | | ----------------- | -------- | --------------------------------------------------------------------------------------------------- | | `app_name` | yes | Name of the AppSignal application. | | `app_environment` | yes | Environment. | | `metric_name` | yes | Name of the metric. | | `metric_type` | yes | `COUNT`, `COUNTER`, `GAUGE`, `MEAN`, `P90`, or `P95`. Use `get_metric_tags` to find the valid type. | | `start` | yes | Start of time range in ISO 8601 format. | | `end` | yes | End of time range in ISO 8601 format. | | `tags` | no | Tag filters, e.g. `[{"key": "hostname", "value": "web*"}]`. Supports `*` wildcards. | *** #### `get_metrics_list` Get an aggregated value for a metric over a time range. Returns a single aggregated value rather than a point-by-point timeseries. Useful for summary views. | Parameter | Required | Description | | ----------------- | -------- | ---------------------------------------------------------------- | | `app_name` | yes | Name of the AppSignal application. | | `app_environment` | yes | Environment. | | `metric_name` | yes | Name of the metric. | | `metric_type` | yes | `COUNT`, `COUNTER`, `GAUGE`, `MEAN`, `P90`, or `P95`. | | `start` | yes | Start of time range in ISO 8601 format. | | `end` | yes | End of time range in ISO 8601 format. | | `tags` | no | Tag filters, e.g. `[{"key": "hostname", "value": "frontend1"}]`. | *** ### Dashboards #### `manage_dashboard` Create or update an AppSignal dashboard. This tool manages dashboard metadata only (title and description). Use `create_dashboard_visual` and `update_dashboard_visual` to add charts. | Parameter | Required | Description | | ----------------- | -------- | -------------------------------------------------------------------------- | | `app_name` | yes | Name of the AppSignal application. | | `app_environment` | yes | Environment. | | `title` | yes | Dashboard title. | | `description` | no | Description of the dashboard's purpose and contents. | | `id` | no | Dashboard ID for updating an existing dashboard. Omit to create a new one. | *** #### `create_dashboard_visual` Add a new chart or graph to an existing dashboard. Use `discover_metrics` or `get_metrics_list` to find available metrics first. | Parameter | Required | Description | | ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ | | `app_name` | yes | Name of the AppSignal application. | | `app_environment` | yes | Environment. | | `dashboard_id` | yes | ID of the dashboard to add the visual to. | | `title` | yes | Chart title. | | `metrics` | yes | Array of metrics to display. Each requires `name`, `fields` (e.g. `mean`, `p90`, `p95`, `count`), and optionally `tags`. | | `description` | no | Additional context about the visual. | | `display` | no | `line` (default), `area`, or `area_relative`. | | `line_label` | no | Custom label for chart lines. Supports `%name%`, `%field%`, and `%tag%` replacements. | | `format` | no | Value format, e.g. `duration`, `size`, `percentage`. | | `draw_null_as_zero` | no | Whether to draw missing data points as zero. Default: `false`. | | `min_y_axis` | no | Minimum Y-axis value. | | `tags` | no | Global tags applied to all metrics in this visual. | *** #### `update_dashboard_visual` Update an existing chart or graph on a dashboard. All fields are optional except the identifiers. Unspecified fields keep their current values. If `metrics` is provided, it replaces all existing metrics on that visual. | Parameter | Required | Description | | ------------------- | -------- | ------------------------------------------------------------------------------------- | | `app_name` | yes | Name of the AppSignal application. | | `app_environment` | yes | Environment. | | `visual_id` | yes | ID of the visual component to update. | | `title` | no | New title. Current title is kept if not provided. | | `description` | no | New description. Set to an empty string to remove. | | `metrics` | no | Updated metrics array. Replaces all existing metrics if provided. | | `display` | no | `line`, `area`, or `area_relative`. | | `line_label` | no | Custom label for chart lines. Supports `%name%`, `%field%`, and `%tag%` replacements. | | `format` | no | Value format, e.g. `duration`, `size`, `percentage`. | | `draw_null_as_zero` | no | Whether to draw missing data points as zero. | | `min_y_axis` | no | Minimum Y-axis value. | | `tags` | no | Global tags. Replaces existing global tags if provided. | *** ## Token permissions Each MCP token has configurable permissions by toolset: `app`, `exceptions`, `performance`, `metrics`, `anomalies`, `dashboards`, `logging`. Each toolset can be set to `read`, `write`, or disabled. Tokens can also be scoped to specific applications and set to automatically expose new tools as they are added. To generate a token: 1. Select your profile icon. 2. Go to **Account Settings**. 3. Select **MCP Tokens** to create a new token. *** ## Missing a tool? If your AI agent or editor can't accomplish something you'd expect to be possible, let it know. AppSignal MCP includes a built-in feedback mechanism that logs requests for capabilities that don't yet exist — this helps the AppSignal team prioritize what to build next. You can also post feature requests in the Discord community.