> For the complete documentation index, see [llms.txt](https://docs.qpoint.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.qpoint.io/guides/qplane-guides/mcp-tools-reference.md).

# MCP Tools Reference

Complete reference for all MCP tools available in the Qpoint integration. Use these tools through your MCP client (Claude Desktop, Cursor, etc.) by asking natural language questions—the AI assistant translates your queries into the appropriate tool calls.

***

## Common Parameters

All tools share these common input formats:

### Timestamps

Use RFC 3339 format for time parameters:

```
2026-02-12T10:30:00Z
```

* `startTimestamp` defaults to 24 hours ago
* `endTimestamp` defaults to now

### Granularity

For time-series data, specify aggregation granularity:

* `minute` — per-minute resolution
* `5minutes` — 5-minute buckets
* `15minutes` — 15-minute buckets
* `hour` — hourly aggregation
* `day` — daily aggregation
* `week` — weekly aggregation
* `month` — monthly aggregation
* `year` — yearly aggregation

If omitted, granularity is auto-detected based on the time range.

### Tags

Key-value metadata in `key:value` format:

```
env:prod
bin:curl
protocol:http2
```

Use `key:` (with colon, no value) to match any resource with that tag key.

### Labels

Simple string identifiers for filtering:

```
user-shell
is-root
direct-ip
unencrypted
deprecated-tls
unknown-tls
```

***

## Connections

Network connections observed by Qtap. Each connection represents a TCP session between your application and an external endpoint.

### Available Tools

| Tool                    | Description                       |
| ----------------------- | --------------------------------- |
| `count_connections`     | Total connection count            |
| `list_connections`      | List individual connections       |
| `get_connection`        | Get a specific connection by ID   |
| `histogram_connections` | Connection counts over time       |
| `connection_frequency`  | Most frequent connection patterns |
| `connection_endpoints`  | Endpoints by connection count     |
| `connection_attr_vals`  | Distinct values for a field       |
| `connection_tags`       | Available tag keys                |
| `connection_tag_vals`   | Values for a specific tag         |

### Fields

| Field                     | Description                                        |
| ------------------------- | -------------------------------------------------- |
| `connectionId`            | Unique connection identifier                       |
| `endpointId`              | Destination domain (e.g., `api.example.com`)       |
| `direction`               | `egress-external`, `egress-internal`, or `ingress` |
| `timestamp`               | Connection start time                              |
| `finalized`               | Whether the connection is complete                 |
| `tags[]`                  | Key-value metadata                                 |
| `labels[]`                | String labels                                      |
| `sourceAddress`           | Origin IP address                                  |
| `sourcePort`              | Origin port                                        |
| `sourceExe`               | Path to the executable                             |
| `sourceHostname`          | Hostname of the source machine                     |
| `sourceSystemUserId`      | UID of the process owner                           |
| `destinationAddress`      | Peer endpoint IP                                   |
| `destinationPort`         | Peer endpoint port                                 |
| `bytesSent`               | Bytes sent                                         |
| `bytesReceived`           | Bytes received                                     |
| `tlsVersion`              | TLS version used                                   |
| `tlsProbeIntrospected`    | Whether TLS was successfully hooked                |
| `tlsProbeTypesDetected[]` | TLS libraries detected (`openssl`, `gotls`, etc.)  |
| `qpointAgent`             | Agent identifier                                   |
| `instanceId`              | Instance identifier                                |
| `qpointHostname`          | Agent hostname                                     |

### Filter Fields

**Exact match:** `endpointId`, `connectionId`, `direction`, `qpointAgent`, `sourceAddress`, `sourcePort`, `sourceExe`, `sourceHostname`, `destinationAddress`, `destinationPort`, `tlsVersion`

**Fuzzy search:** `endpointIsh` (substring match on endpoint)

### Example Queries

> "List all connections to stripe.com in the last hour"

> "How many connections used TLS 1.2 yesterday?"

> "Show connections from executable /usr/bin/curl"

> "What endpoints did hostname prod-server-01 connect to?"

***

## Requests

Individual HTTP requests observed within connections. Provides detailed request/response information including methods, paths, status codes, and timing.

### Available Tools

| Tool                         | Description                          |
| ---------------------------- | ------------------------------------ |
| `count_requests`             | Total request count                  |
| `list_requests`              | List individual requests             |
| `get_request`                | Get a specific request by ID         |
| `histogram_requests`         | Request counts over time             |
| `request_frequency`          | Most frequent request patterns       |
| `request_endpoints`          | Endpoints by request count           |
| `request_attr_vals`          | Distinct values for a field          |
| `request_tags`               | Available tag keys                   |
| `request_tag_vals`           | Values for a specific tag            |
| `request_duration_aggregate` | Avg/min/max duration statistics      |
| `request_duration_line`      | Duration metrics over time           |
| `request_tag_count`          | Count distinct tag value occurrences |
| `request_tag_line`           | Tag value trends over time           |

### Fields

| Field             | Description                       |
| ----------------- | --------------------------------- |
| `requestId`       | Unique request identifier         |
| `connectionId`    | Parent connection ID              |
| `endpointId`      | Destination domain                |
| `vendorId`        | Vendor identifier                 |
| `direction`       | Traffic direction                 |
| `timestamp`       | Request time                      |
| `url`             | Full request URL                  |
| `path`            | URL path                          |
| `method`          | HTTP method (`GET`, `POST`, etc.) |
| `status`          | HTTP status code                  |
| `duration`        | Request duration in microseconds  |
| `contentType`     | Response content type             |
| `category`        | Request category                  |
| `agent`           | User agent string                 |
| `tags[]`          | Key-value metadata                |
| `authTokenMask`   | Masked auth token                 |
| `authTokenHash`   | Auth token hash                   |
| `authTokenSource` | Where auth token was found        |
| `authTokenType`   | Type of auth token                |
| `bytesSent`       | Request body size                 |
| `bytesReceived`   | Response body size                |

### Filter Fields

**Exact match:** `endpointId`, `connectionId`, `vendorId`, `direction`, `method`, `path`, `contentType`, `agent`, `status`, `authTokenMask`, `authTokenHash`, `authTokenSource`, `authTokenType`, `dataType`

**Fuzzy search:** `endpointIsh`, `vendorIsh`, `pathIsh`

### Example Queries

> "Show me all POST requests to api.example.com/v1/payments"

> "What requests returned 500 errors today?"

> "List requests with content-type application/json"

> "Which API paths have the highest request volume?"

***

## Traffic

Aggregated traffic metrics across connections, requests, and issues. Provides high-level counts, performance, availability, and bandwidth metrics with breakdowns by location and geography.

### Available Tools

**Counts & Summaries:**

| Tool                           | Description                 |
| ------------------------------ | --------------------------- |
| `traffic_count`                | Total traffic count         |
| `traffic_duration`             | Traffic duration statistics |
| `traffic_availability`         | Availability metrics        |
| `traffic_summary`              | Overall traffic summary     |
| `traffic_summary_performance`  | Performance summary         |
| `traffic_summary_availability` | Availability summary        |
| `traffic_summary_bandwidth`    | Bandwidth summary           |

**Time Series:**

| Tool                        | Description                    |
| --------------------------- | ------------------------------ |
| `traffic_line`              | Traffic metrics over time      |
| `traffic_line_performance`  | Performance metrics over time  |
| `traffic_line_availability` | Availability metrics over time |
| `traffic_line_bandwidth`    | Bandwidth metrics over time    |

**Location & Geographic:**

| Tool                             | Description                   |
| -------------------------------- | ----------------------------- |
| `traffic_locations`              | Traffic breakdown by location |
| `traffic_locations_performance`  | Performance by location       |
| `traffic_locations_availability` | Availability by location      |
| `traffic_locations_bandwidth`    | Bandwidth by location         |
| `traffic_geo_countries`          | Traffic by country            |
| `traffic_geo_regions`            | Traffic by region             |
| `traffic_geo_cities`             | Traffic by city               |

### Time-Series Group Values

**Performance metrics:** `connections_per_second`, `connections_per_minute`, `requests_per_second`, `requests_per_minute`, `avg_duration`, `max_duration`, `p_99_duration`, `p_95_duration`, `p_50_duration`

**Availability metrics:** `connections`, `requests`, `issues`, `issues_per_second`, `issues_per_minute`, `avg_availability`, `p_99_availability`, `p_95_availability`

**Bandwidth metrics:** `total_bandwidth`, `total_bytes_received`, `total_bytes_sent`, `bytes_received_per_second`, `bytes_sent_per_second`, `bytes_received_per_minute`, `bytes_sent_per_minute`, `p_99_bytes_received`, `p_99_bytes_sent`, `max_bytes_received`, `max_bytes_sent`

### Filter Fields

Combines connection, request, and issue filters:

**Exact match:** `endpointId`, `vendorId`, `connectionId`, `direction`, `qpointAgent`, `sourceAddress`, `sourcePort`, `sourceExe`, `sourceHostname`, `destinationAddress`, `destinationPort`, `tlsVersion`, `method`, `path`, `contentType`, `agent`, `status`, `authTokenMask`, `authTokenHash`, `authTokenSource`, `authTokenType`, `dataType`, `error`, `mitigated`

**Fuzzy search:** `endpointIsh`, `vendorIsh`, `pathIsh`, `errorIsh`

### Example Queries

> "Give me a traffic summary for the past week"

> "Show requests per minute for api.stripe.com over the last 24 hours"

> "What's the p95 latency for the /api/checkout endpoint?"

> "Which countries is my API traffic going to?"

> "Compare bandwidth usage between staging and production"

***

## Issues

API issues detected by policy rules—schema violations, auth failures, rate limits, errors, and more.

### Available Tools

| Tool               | Description                  |
| ------------------ | ---------------------------- |
| `count_issues`     | Total issue count            |
| `list_issues`      | List individual issues       |
| `histogram_issues` | Issue counts over time       |
| `issue_frequency`  | Most frequent issue patterns |
| `issue_endpoints`  | Endpoints by issue count     |
| `issue_errors`     | Error types and counts       |
| `issue_attr_vals`  | Distinct values for a field  |

### Fields

| Field                 | Description                         |
| --------------------- | ----------------------------------- |
| `timestamp`           | When the issue was detected         |
| `connectionId`        | Parent connection ID                |
| `endpointId`          | Destination domain                  |
| `vendorId`            | Vendor identifier                   |
| `requestId`           | Associated request ID               |
| `direction`           | Traffic direction                   |
| `error`               | Error message                       |
| `url`                 | Full request URL                    |
| `path`                | URL path                            |
| `method`              | HTTP method                         |
| `status`              | HTTP status code                    |
| `mitigated`           | Whether the issue was mitigated     |
| `tags[]`              | Key-value metadata                  |
| `triggerConditions[]` | Conditions that triggered the issue |
| `triggerReasons[]`    | Reasons for the trigger             |

### Filter Fields

**Exact match:** `endpointId`, `vendorId`, `connectionId`, `direction`, `method`, `status`, `path`, `error`, `mitigated`

**Fuzzy search:** `endpointIsh`, `vendorIsh`, `pathIsh`, `errorIsh`

### Example Queries

> "How many 500 errors occurred today?"

> "Show me all rate limit issues (429 status) from the past week"

> "Which endpoints have the most authentication failures?"

> "List unmitigated issues for api.example.com"

> "What error types are we seeing on the payments endpoint?"

***

## PII

Personally Identifiable Information detected in API traffic. Identifies sensitive data exposure including emails, phone numbers, credit cards, and more.

### Available Tools

| Tool            | Description                   |
| --------------- | ----------------------------- |
| `count_pii`     | Total PII detection count     |
| `pii_summary`   | Summary of PII types detected |
| `histogram_pii` | PII detections over time      |
| `pii_frequency` | Most frequent PII patterns    |
| `pii_attr_vals` | Distinct values for a field   |

### Fields

| Field          | Description                                                |
| -------------- | ---------------------------------------------------------- |
| `entityType`   | Type of PII (`email`, `phone_number`, `credit_card`, etc.) |
| `score`        | Confidence score of the detection                          |
| `endpointId`   | Destination domain                                         |
| `vendorId`     | Vendor identifier                                          |
| `connectionId` | Parent connection ID                                       |
| `direction`    | Traffic direction                                          |

### Filter Fields

**Exact match:** `endpointId`, `vendorId`, `connectionId`, `direction`, `entityType`, `score`

**Fuzzy search:** `endpointIsh`, `vendorIsh`

### Example Queries

> "Is there any PII detected in outbound traffic?"

> "Show me all credit card detections from the past week"

> "Which endpoints have the most PII exposure?"

> "List high-confidence (score > 0.9) email detections"

> "How many phone numbers were detected in traffic to third-party APIs?"

***

## Tips for Effective Querying

### Use `limit` for Large Results

List operations return full objects and can be large. Use `limit` to control result size:

> "List the last 10 requests to stripe.com"

### Start with Counts

Before listing detailed records, get a count to understand the volume:

> "How many connections to api.example.com occurred today?"

Then refine:

> "List the 20 most recent connections to api.example.com"

### Use `attr_vals` for Discovery

Find what values exist for a field before filtering:

> "What unique endpoints have connections?"

> "What HTTP methods are being used?"

### Combine Filters

Narrow results by combining multiple criteria:

> "Show POST requests to /api/payments that returned 500 errors in the last hour"

### Leverage Fuzzy Search

Use `*Ish` filters when you don't know the exact value:

> "Find traffic to endpoints containing 'stripe'"

Uses `endpointIsh` for substring matching.

### Time Range Best Practices

* Be specific: "in the last hour" vs "recently"
* Use relative ranges for recent data: "today", "yesterday", "past week"
* Use absolute timestamps for precise investigation: "between 2pm and 3pm on February 15th"


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.qpoint.io/guides/qplane-guides/mcp-tools-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.