---
title: "9apes MCP Server Tools Reference"
description: "Reference for the read-only 9apes MCP tools - inputs, time windows, filters, limits, result format, and how to interpret CI duration statistics."
url: https://9apes.com/docs/mcp-server/tools/
---

# 9apes MCP Server Tools Reference

The [9apes MCP server](https://9apes.com/docs/mcp-server/) exposes nine read-only tools. Your assistant discovers them automatically; this page is for checking what they can and cannot answer.

## Tools

| Tool | Inputs | Returns |
| --- | --- | --- |
| `9apes_get_context` | None | Connected organization, user, granted scopes, and limits |
| `9apes_get_github_status` | None | GitHub App connection details for the organization |
| `9apes_get_filter_values` | Optional `window`, `filters` | Repositories, branches, and workflows seen in the window |
| `9apes_list_runs` | Optional `window`, `filters`, `page` (default 1), `per_page` (default 30, max 100) | Runs, newest first, with pagination details |
| `9apes_get_run_stats` | Optional `window`, `filters` | Run count and P50, P75, P95, and max duration, overall and per UTC day |
| `9apes_get_job_stats` | Optional `window`, `filters` | Duration statistics per job group and per step |
| `9apes_get_run_jobs` | `run_ids` (1 to 30 GitHub run IDs) | Jobs and steps for those runs, including every recorded attempt |
| `9apes_rank_jobs` | Optional `window`, `filters`, `metric` (default `p95`), `direction` (default `desc`), `limit` (default 20, max 50) | Job groups ranked by one duration statistic |
| `9apes_compare_windows` | `current`, `baseline`; optional `filters`, `kind` (`runs` or `jobs`), `metric` (default `p95`) | Metric changes between two equal-length windows |

`metric` is one of `p50`, `p75`, `p95`, or `max`. `direction` is `asc` or `desc`.

## Time windows

```json
{
  "window": {
    "start_time": "2026-10-01T00:00:00Z",
    "end_time": "2026-10-08T00:00:00Z"
  }
}
```

- Times need a UTC offset and are normalized to UTC.
- Windows are half-open: a run created exactly at `end_time` belongs to the next window.
- A window spans at most 31 days. Without one, tools use the last 7 days.
- For `9apes_compare_windows`, `current` and `baseline` must be the same length and must not overlap. Adjacent windows are fine: end the baseline exactly where the current window starts.

## Filters

```json
{
  "filters": {
    "repo_names": ["backend"],
    "head_branches": ["main"],
    "workflow_ids": [12345]
  }
}
```

| Filter | Accepts | Limit |
| --- | --- | --- |
| `repo_names` | Short repository names, not `owner/repo` | 20 |
| `head_branches` | Branch names | 20 |
| `workflow_ids` | Positive GitHub workflow IDs | 30 |

Use `9apes_get_filter_values` to find valid values. Status, conclusion, runner label, and job-name filters are not supported. The organization always comes from your connection; no tool takes an organization argument.

## Limits

- Each tool call has a 15-second deadline.
- Results are capped at 64 KiB. A larger result returns `response_limit`; narrow the window, add filters, or lower `per_page`.
- Pages are not snapshots. New runs can shift results between pages.

## Results

Each tool returns structured content in the same envelope:

```json
{
  "success": true,
  "data": {},
  "error": null,
  "meta": {
    "availability": "complete",
    "as_of": "2026-10-08T12:00:00.000Z",
    "warnings": [],
    "untrusted_fields": []
  }
}
```

`meta.availability` is `complete`, `partial`, or `unavailable`. `meta` also lists the exact window, filters, and source queries behind the result, so an assistant can cite where a number came from. `as_of` is when the query ran, not how fresh the ingested data is.

## Reading the numbers

- P50 is the median. A `null` duration means unknown; it is never treated as zero.
- Run duration is the time from start to last update. It does not include queue time and is not a critical-path measurement.
- Job groups combine the short repository name and job name, so two workflows with the same job name can merge. Aggregates do not include sample counts.
- Run statistics select by run creation time; job statistics select by job creation time, so the two can differ near a window edge.
- Timing data alone does not prove why something is slow. Treat conclusions as hypotheses to check.

> **Repository-controlled text:** Run titles, branch names, workflow names, job and step names, and runner labels are set by anyone who can open a pull request. The server strips control characters and caps their length, and lists them in `meta.untrusted_fields`, so assistants treat them as data rather than instructions.

## Not available

Logs, workflow YAML, cache hit rates, CPU and memory telemetry, failure and flakiness rates, billing data, and any action that changes state are not exposed by these tools.