> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vexlo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP tools

> Exact inputs, limits and result conventions for Vexlo's MCP read tools.

The MCP server exposes eleven read tools. Arguments use camelCase, such as `traceId`; result
fields retain the HTTP API's spelling, such as `trace_id`. Successful results contain one MCP
text block holding JSON. API failures contain a JSON error object and `isError: true`.

Use [Connect an agent](https://docs.vexlo.ai/agents/connect.md) for installation and host setup.

## Tool index

| Tool | Returns | Required arguments |
| - | - | - |
| `vexlo_search_traces` | Filtered trace summaries. | None. |
| `vexlo_check_trace_status` | Summaries for specified trace IDs, with missing-ID reporting. | `traceIds`. |
| `vexlo_find_related_traces` | Traces sharing tags with the selected trace. | `traceId`. |
| `vexlo_list_functions` | Recorded function catalog. | None. |
| `vexlo_list_tags` | Tag keys and emitting services. | None. |
| `vexlo_check_coverage` | Recording and loss information by service. | None. |
| `vexlo_check_health` | Server storage and reporting health. | None. |
| `vexlo_get_trace` | Call structure, attempts, timing and value previews. | `traceId`. |
| `vexlo_get_function` | One function and observed callers/callees. | `service`, `name`. |
| `vexlo_get_values` | Selected recorded input/output/error/log bytes. | `traceId`, `path`. |
| `vexlo_get_function_examples` | Retained executions of a function, as previews or values. | `service`, `name`. |

## Shared filters, limits and results

Inputs reject unrecognized keys. Every `limit` must be a positive integer within the tool's
stated ceiling.

`team` is an optional array of team IDs for scoped discovery and function tools. Omission uses
the token's accessible team set. Requested teams cannot widen access. Unknown teams are dropped
with `scope_note`; if none are accessible, the client skips the query and returns an empty
scoped result with that note.

For tools with an environment object, use one of these input forms:

```json theme={"system"}
{"environment": {"named": ["staging"]}}
```

```json theme={"system"}
{"environment": {"unset": true}}
```

Omit `environment` for no environment filter. `vexlo_list_tags` differs: its environment input
is an array of names, such as `{"environment":["staging"]}`; it cannot select unset environments.
Trace-ID reads take no discovery scope filters; the server still enforces the token's scope.

Page ceilings are bounded by the server's capabilities as described per tool. Pass a returned
`next_cursor` back as `cursor`, and stop at `null`. A positional cursor does not create a stable
snapshot of data still receiving records.

Returned root status, root name or duration can be absent before completion. A function row's
`team` can be absent for an effective multi-team query. Treat these omissions as data;
do not require every result to have the fields of a completed, single-team example.

## Search traces

`vexlo_search_traces` accepts only optional arguments:

| Argument | Type / behavior |
| - | - |
| `team` | Array of team IDs. |
| `environment` | Named/unset object described above. |
| `service` | Array of service names. |
| `since`, `until` | Date-time strings. |
| `completeness` | `running`, `complete`, `partial` or `abandoned`. |
| `rootStatus` | `ok` or `error` for the entry point. |
| `hasError` | Boolean; includes recovered call failures. |
| `rootFunction`, `function` | Exact fully qualified function name, at the root or anywhere in the trace. |
| `durationMinMs`, `durationMaxMs` | Nonnegative integer milliseconds. |
| `tagKey`, `tagValue` | Tag filter; a value without a key searches across keys. |
| `limit` | Integer, default `10`; maximum is the lower of `100` and server `search_limit_max`. |
| `cursor` | Previous page's `next_cursor`. |

The result contains `items`, applied `limit`, `next_cursor` and an applicable `scope_note`.
Use the returned `trace_id` with `vexlo_get_trace`. Function-name matching is exact.
`since` and `until` are inclusive bounds on the server's first receipt time, not the SDK's
execution start time; see [HTTP search](https://docs.vexlo.ai/reference/http-search.md#find-requests).

## Check known trace IDs

`vexlo_check_trace_status` takes `traceIds`, an array of 1 to 100 IDs, and no search filters.
It returns summary `items`, the applied `limit` and `next_cursor`.

When requested IDs are absent from the result, `not_returned` reports them in the caller's
order. The field is omitted when every ID is returned. It does not distinguish nonexistent
traces from traces outside the read token's scope.

## Find related traces

`vexlo_find_related_traces` takes required `traceId` and these optional arguments:

| Argument | Behavior |
| - | - |
| `windowHours` | Integer from `1` to `168`, default `24`. |
| `limit` | Default is server `search_limit_default`, bounded by the lower of `100` and server `search_limit_max`. |
| `cursor` | Continue a previous page. |

The result includes `relation`, `searched_tag_keys`, searched `window`, `items`, `limit` and
`next_cursor`. An applicable `note` warns when an empty result's anchor trace lies outside
the searched window. Shared tags relate recordings; they do not establish that one service
called another.

## List functions and tags

| Tool | Optional inputs |
| - | - |
| `vexlo_list_functions` | `team`, environment object, singular `service`, exact `name`, `limit`, `cursor`. |
| `vexlo_list_tags` | `team`, environment-name array, singular `service`, `limit`, `cursor`. |

The maximum list limit is the lower of `200` and server `search_limit_max`. The default is
server `search_limit_default`, clamped to that ceiling. Both return `items`, `limit`,
`next_cursor` and applicable scope information.

For function discovery, copy the exact service/name from catalog results. The catalog's
`is_entry_point` flag requires a service filter and is computed across that service's
environments. Verify scoped entry-point observations through `vexlo_get_function`; see the
[HTTP metadata contract](https://docs.vexlo.ai/reference/http-search.md#find-functions-and-observed-dependencies).

The server applies its function `name` equality filter after pagination, so an empty filtered
page can still have a cursor. Follow it before concluding that no function matches.

## Check coverage and health

`vexlo_check_coverage` and `vexlo_check_health` accept optional `team`, environment object and
singular `service`. They take no cursor or list limit.

Coverage reports observed services, recording counts, observed function counts and record
loss. Health reports server storage, reported loss and recent service activity. These describe the
selected scope, not proof that every application path is instrumented or delivered.

## Read a trace

`vexlo_get_trace` takes required `traceId` and optional:

| Argument | Behavior |
| - | - |
| `order` | `structural` by default, or `slowest_first`. |
| `cursor` | Continue the prior call's step page. |

The response contains trace metadata, `steps`, `limit`, `next_cursor`, completeness and
recording-quality information. Each completed attempt can include input/output/error/log
previews. Retrieve full values with `vexlo_get_values`.

`steps` is one page of at most 500. Follow cursors to `null`, count distinct paths against the
newest `step_count`, and restart without a cursor while they disagree. A trace still receiving
records remains a changing observation even when a cursor walk reaches its end.

An `in_flight` attempt carries `attempt`, `started_us` and `status`, without completed
duration or slots. A step with no completed attempt sorts last in `slowest_first`. A retrying
step with completed attempts ranks by their accumulated duration, so an open attempt can
appear on any page. Do not infer missing-call or hung-call counts from a single page.

## Read a function

`vexlo_get_function` requires `service` and `name`, both nonempty strings. It accepts optional
`team` and the environment object. The result describes the function and its observed callers
and callees. Those relationships connect recorded calls; they are not an exhaustive static
dependency list.

Use `vexlo_get_function_examples` for recorded executions and `vexlo_get_trace` for their
surrounding call graphs. See [Understand function usage](https://docs.vexlo.ai/guides/function-usage.md).

## Retrieve selected values

`vexlo_get_values` takes:

| Argument | Required | Behavior |
| - | - | - |
| `traceId` | Yes | Nonempty trace ID. |
| `path` | Yes | Nonempty array of paths copied from trace detail; maximum is server `values_max_paths`, `8` in the captured server. |
| `slots` | No | Nonempty array drawn from `input`, `output`, `error`, `logs`. Omit for all present slots. |

The root path is the empty string, `""`; it is a valid array entry. Results include `values`
and `unknown_paths`. The `value` field is encoded data in a string, including when the
`encoding` is `json`.

A readable zero-length payload omits `value` and `bytes_count`, but retains `encoding` and
`truncated`. The MCP result preserves these fields rather than filling in an empty `value`.

This API selects paths and slots, not numbered attempts. It can return repeated path/slot
entries from several attempts without an attempt identifier. Do not assign those entries to
retry numbers by array position. Use trace detail's attempt-specific previews and status where
that identity matters.

A `pending` slot reads as `stored` when its bytes are readable. Without readable bytes it
remains `pending`, which does not establish why the bytes are absent or whether a later read
will find them. For slots recorded as `stored`, a full-value read returns `expired` when bytes
are unavailable. This does not prove that the bytes previously arrived.
See [Inspect recorded values](https://docs.vexlo.ai/guides/values.md) and
[HTTP traces and values](https://docs.vexlo.ai/reference/http-traces.md).

## Retrieve function examples

`vexlo_get_function_examples` requires `service` and `name`, and accepts:

| Argument | Behavior |
| - | - |
| `team` | Optional array of team IDs. |
| `environment` | Optional named/unset object. |
| `limit` | Integer from `1` to `5`, default `5`. |
| `includeValues` | Boolean, default `false`; request full stored values when true. |

The response contains the function identity and up to five retained examples, with previews
by default. It has no cursor. Environment filtering selects from existing retained examples;
it does not establish a complete history or create an exhaustive sample for that environment.
Requesting `includeValues` does not guarantee a `value` field. If bytes cannot be returned,
inspect the slot's state and preview instead.

The client normalizes an empty slot `state` to `not_captured`; an absent input/output key stays
absent.

## Errors and changing observations

Tool failures set MCP `isError: true` and include a JSON error with `kind`. Mapped kinds include
`authentication_failed`, `wrong_role`, `not_found`, `invalid_arguments`,
`too_many_values_requested`, `rate_limited`, `server_error`, `malformed_response` and
`network_error`. Preserve the returned server code/message when reporting the failure.

Startup failures occur before tools are available; use [Connect an agent](https://docs.vexlo.ai/agents/connect.md) for their
exit codes. For successful reads, keep application status, recording completeness and value
availability separate. None substitutes for the others.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.