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

# AI agent and MCP

> How the AI Studio agent and external MCP clients read your attack surface with the query_attack_surface tool

The [AI Studio](https://docs.oasm.io/ai-studio/overview.md) agent and the [MCP server](https://docs.oasm.io/settings/mcp.md) read the attack surface through Attack Surface Query. Ask in plain language — *"which targets do I have?"*, *"what is exposed on api.example.com?"*, *"which hosts serve HTTP but not HTTPS?"*, *"rank my hosts by critical findings"* — and the agent writes the query.

## The tools

| Tool | What it does |
| - | - |
| `query_attack_surface` | Runs a batch of queries — the same JSON as `POST /api/attack-surface/query` — plus an optional `projectId` |
| `describe_attack_surface` | Lists the resources, fields, operators and relations the caller may read |

Both are read-only, so they run without an approval prompt even in manual approval mode. In **Agent** mode, like every tool, they run once a step of an approved plan is in progress.

`query_attack_surface` replaces the earlier per-topic lookups. Agent definitions and settings that still name an old tool keep working: the name now points to `query_attack_surface`.

| Earlier tool | Now |
| - | - |
| `retrieve_targets` | `from: "targets"` |
| `enumerate_assets`, `examine_target_assets`, `inspect_asset` | `from: "hosts"` or `"services"` (filter by `target.value`, `value` or `id`) |
| `list_network_ports` | `from: "services"` |
| `fingerprint_technologies` | `from: "technologies"` |
| `verify_tls_settings` | `from: "tls"` |
| `discover_vulnerabilities` | `from: "vulnerabilities"` |

> [!NOTE]
>
> Full details of one finding — description, proof of concept, remediation, evidence, timeline — still come from `investigate_vulnerability`, and the dashboard score and trends from `gather_statistics`.

## How the agent learns the language

* **The tool description** carries the rules and the exact field names of every resource, generated from the same catalog the server validates against, so the model never has to guess a name.
* **The `attack-surface-query` skill** (see [Skills](https://docs.oasm.io/ai-studio/settings/skills.md)) teaches the full language — operators, time, aggregates, paging, limits, the errors and how to fix them — with ready-made queries. The agent loads it before its first query of a conversation, and every built-in agent declares it.
* **Errors are written for the model**: an unknown field lists the valid fields of that resource, a field that cannot be grouped lists the ones that can, and a query over budget says what to change. The agent fixes the whole call and sends it once more.

## Permissions and scope

* The agent acts for the member running the conversation: each resource requires that member's read permission (`asset.read`, `vulnerability.read`, `target.read`).
* A **project chat** locks every query to the project's assets; a `projectId` the model passes cannot leave it.
* On the **MCP server**, which authenticates with the workspace API key and has no member, the tool reads with `asset.read`, `vulnerability.read` and `target.read`.

## Limits

The agent and MCP clients run under tighter limits than the API: 5 queries per call, 200 rows per query, 3 includes, 20 children per include, 20 conditions per filter, 3 seconds per statement, 64 KB per answer, and no large HTTP fields (`body`, headers). Report mode is not available to them. Everything else in the language is theirs too: nested filters, relation tests, conditional aggregates, `having` and filled time series. See [Paging, limits and cost](https://docs.oasm.io/attack-surface-query/paging-and-limits.md#limits).

## Using it from an MCP client

Connect the client as described in [MCP Server](https://docs.oasm.io/settings/mcp.md), then let the assistant call `describe_attack_surface` and `query_attack_surface`. A call looks like:

```json theme={null}
{
  "queries": {
    "exposed": {
      "from": "services",
      "select": ["host.value", "port", "http.title"],
      "where": { "logic": "and", "items": [{ "field": "port", "op": "in", "value": ["3389", "445", "6379"] }] }
    }
  }
}
```

Query errors come back as a normal result, `{ "error": { "code", "message", "issues", "hints" } }`, so the assistant can read them and retry.

> [!WARNING]
>
> The earlier tool names (`enumerate_assets`, `retrieve_targets`, …) are no longer on the MCP server. An MCP client or script that called them must switch to `query_attack_surface`.


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