# 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"