@grepr/cli 1.11.3 → 1.11.5-173e2da

package/build/dist/docs-index/41409011-99d2-45ed-98e7-917c2e0ec0e7.txt

@@ -0,0 +1,142 @@
+Connect Claude or Claude Code to the Grepr MCP server with OAuth sign-in, or connect any MCP client with a service account access token.
+
+# Connect to the Grepr MCP server
+
+Grepr provides a remote Model Context Protocol server, or MCP server, that lets AI assistants work with your Grepr organization. The server provides tools to list pipelines, browse datasets and templates, query logs, validate SQL and Grok rules, and propose pipeline changes. Every tool call is authorized with the same role-based permissions as the Grepr UI and REST APIs.
+
+The MCP server is available at the following endpoints:
+
+| Region | Endpoint |
+| --- | --- |
+| US | `https://app.grepr.ai/mcp` |
+| EU | `https://app.euc1.grepr.ai/mcp` |
+
+The examples on this page use the US endpoint. If your organization is in the EU region, replace the endpoint and use the EU client ID.
+
+You can authenticate in two ways:
+
+* OAuth sign-in: You sign in interactively with your Grepr user account. Use this for Claude and Claude Code.
+* Service account credentials: Your client authenticates as a Grepr service account. Use this for Claude Tag in Slack, for automation, and for MCP clients that do not support the OAuth sign-in flow.
+
+## Sign in with OAuth
+
+Grepr registers a dedicated OAuth client for each supported MCP client. To connect, configure your MCP client with the Grepr endpoint and the matching client ID from the following table, then sign in with your Grepr user account. When the sign-in page prompts for an organization, enter your Grepr organization name.
+
+| MCP client | US client ID | EU client ID |
+| --- | --- | --- |
+| Claude | `us3sBOgZj6hERktG9yZEVwujaJe3j9L0` | `HOnxCPNGnzdGlfXBM2sff0twoolRnDj9` |
+| Claude Code | `jlCTdLYzDkkTSc2I7MdI0SBw48AOdJM6` | `GlEIcfSbge5gqN4o918fLXKVONP2twBh` |
+
+### Claude
+
+These steps apply to Claude on the web, the Claude desktop apps, and the Claude mobile apps.
+
+1. In Claude, go to **Settings** > **Connectors** and click **Add custom connector**.
+2. Enter `https://app.grepr.ai/mcp` as the URL.
+3. Under **Advanced settings**, enter `us3sBOgZj6hERktG9yZEVwujaJe3j9L0` as the **OAuth Client ID**. Leave the client secret empty.
+4. Complete the sign-in flow with your Grepr user account.
+
+### Claude Code
+
+Add the server with the Grepr client ID and the fixed callback port:
+
+```bash
+claude mcp add --transport http --client-id jlCTdLYzDkkTSc2I7MdI0SBw48AOdJM6 --callback-port 6280 grepr https://app.grepr.ai/mcp
+```
+
+The `--callback-port 6280` flag is required. Without it, Claude Code picks a random port and the sign-in fails with a callback URL mismatch.
+
+Then open Claude Code, run `/mcp`, select `grepr`, and complete the sign-in flow in your browser with your Grepr user account.
+
+## Connect Claude Tag in Slack
+
+Claude Tag is Claude in Slack channels. In a channel, Claude acts as a shared identity that an Owner of your Claude organization configures, not as the person who sends the message. Everyone in a channel that the configuration covers gets the same Grepr access, so connect a dedicated Grepr service account with the narrowest role that fits the channel. Direct messages with Claude in Slack run on your own Claude account and use the Claude connector described earlier on this page.
+
+Before you start, you need:
+
+* The Owner role in your Claude organization. Claude Tag is available on the Claude Team and Enterprise plans.
+* A Grepr service account and its client ID and client secret. See [Manage Grepr service accounts](/admin/service-accounts).
+* The Grepr plugin for Claude Tag: [grepr-claude-tag-plugin.zip](/plugins/grepr-claude-tag-plugin.zip). Claude Tag reaches an MCP server only through a plugin. The plugin contains two files: a manifest, and an `.mcp.json` file that names the US and EU Grepr MCP endpoints.
+
+### Upload the plugin
+
+1. In Claude, go to **Admin settings** > **Plugins** and click **Add plugins**.
+2. Select **Upload a file** and upload `grepr-claude-tag-plugin.zip`.
+
+The plugin is now in your organization's catalog. It does nothing until you turn it on in an access bundle.
+
+### Turn on the plugin and add the credential
+
+An access bundle is the set of credentials and plugins that Claude uses in the channels the bundle covers. The **Default Slack** scope covers every channel in your Slack workspace. To limit Grepr access to one channel, select that channel's scope instead.
+
+1. Go to **Admin settings** > **Claude Tag** and, under **Claude Tag's access**, select the **Slack** tab.
+
+2. Select the **Default Slack** scope, or the channel to connect.
+
+3. Next to **Access bundles**, click the **+** button and select **Create new bundle**, or open the existing bundle.
+
+4. On the **Plugins** tab, turn on **grepr-mcp**.
+
+5. On the **Credentials** tab, click **Connect** next to **Custom tool** and enter the following values:
+
+   \| Field | Value | | --- | --- | | Name | `Grepr` | | Credential type | **OAuth 2.0 client credentials** | | Token URL | `https://auth.grepr.ai/oauth/token`, or `https://auth.eu.grepr.ai/oauth/token` for the EU region | | Client ID | The service account client ID | | Client secret | The service account client secret | | Audience | `service` | | Allowed websites | `app.grepr.ai`, or `app.euc1.grepr.ai` for the EU region |
+
+6. Save the connection and confirm that its status is **Active** on the **Access bundles** page.
+
+> A bundle on a public channel gives its access to anyone who joins the channel. Keep a service account with edit permissions in a bundle on a private channel.
+
+### Test the connection
+
+In a channel the bundle covers, start a new thread and send:
+
+```text
+@Claude list the Grepr pipelines
+```
+
+Threads that started before you turned on the plugin do not pick it up. If Claude reports that a host was blocked by the network egress proxy, add the host it names to the **Allowed websites** of the Grepr connection.
+
+## Authenticate with a service account token
+
+For automation, and for MCP clients that are not in the table and do not support OAuth 2.0 client credentials, authenticate with a service account access token. The MCP endpoint accepts the same access tokens as the Grepr REST APIs.
+
+1. Create a service account. See [Manage Grepr service accounts](/admin/service-accounts).
+
+2. Obtain an access token. See [Authenticate to Grepr REST APIs](/apis/authentication).
+
+3. Configure your MCP client to send the token in the `Authorization` header. Most clients accept a headers object in their MCP server configuration:
+
+   ```json
+   {
+     "headers": {
+       "Authorization": "Bearer <access-token>"
+     }
+   }
+   ```
+
+> The access token expires after 24 hours and has no refresh token, so your client cannot renew it automatically. When the token expires, obtain a new token and update your client configuration. For scheduled automation, obtain a new token at the start of each run.
+
+## Frequently Asked Questions
+
+### What is the Grepr MCP server URL?
+
+The MCP endpoint is https\://app.grepr.ai/mcp for the US region and https\://app.euc1.grepr.ai/mcp for the EU region.
+
+### How do I connect Claude to Grepr?
+
+Add a custom connector in Claude with the URL https\://app.grepr.ai/mcp, and enter the Grepr client ID for Claude under Advanced settings. Then sign in with your Grepr user account.
+
+### Why does the MCP sign-in fail with a callback URL mismatch?
+
+Grepr registers exact OAuth callback URLs. Clients that open the sign-in flow on a local port must use port 6280, for example with the --callback-port 6280 flag in Claude Code.
+
+### Can I use the Grepr MCP server without OAuth?
+
+Yes. The MCP endpoint accepts the same service account access tokens as the Grepr REST APIs. Send the token in the Authorization header as a Bearer token.
+
+### Can I use Grepr from Claude in Slack?
+
+Yes. Upload the Grepr plugin for Claude Tag, turn it on in an access bundle, and add an OAuth 2.0 client credentials connection for app.grepr.ai with a Grepr service account, the token URL https\://auth.grepr.ai/oauth/token, and the audience service.
+
+### Which organization does an MCP session use?
+
+The organization you enter at sign-in, or the organization of the service account that issued the token. The MCP session is scoped to that organization.

package/build/dist/docs-index/4a6f8a4e-ecb3-4eda-82ba-e8ec80059250.txt

@@ -0,0 +1,78 @@
+Two ways to send logs to several vendor accounts, by creating a pipeline for each group or by grouping the reducer and filtering each sink.
+
+# Route logs to several vendor accounts
+
+Your logs do not all belong in the same place. Separate teams, environments, or business units each own an account in your observability platform, and a log has to reach the account that owns it. Each account you send to is its own Grepr integration.
+
+A Grepr pipeline is a free-form processing graph rather than a fixed shape, so you can arrange this in more than one way. Here are two examples, and you can combine them.
+
+## Create a pipeline for each group \[#pipeline-per-group]
+
+Create one pipeline for each group of logs that belongs together, filter its source to that group, and give it the sink for that group's account.
+
+Each pipeline summarizes only its own logs, so you can tune each one on its own. Choose this when the groups need different configurations, or when you want them isolated from each other.
+
+To create a pipeline, see [_](/tutorials/first-pipeline). To limit what one ingests, see [_](/transforms/filter-events).
+
+## Group the reducer and filter each sink \[#grouped-sinks]
+
+Run a single pipeline, add a sink for each account, and filter each sink to that account's logs. Choose this when the groups have the same configuration, and you would rather manage one pipeline than several.
+
+Routing rests on a *routing key*, which is a field whose value names the account a log belongs to, such as `account` or `team`. Two settings act on it: the reducer groups on the key, and each sink filters on it.
+
+Grouping is what makes the filtering correct. A summary carries the values of the fields it was grouped on, so grouping on the routing key gives every summary exactly one account, and each sink's filter then matches its own account and no other.
+
+> Configure the grouping before you add the sinks, because leaving it out fails quietly. Without the routing key in the group-by, logs bound for different accounts aggregate together. A tag then carries every value the merged messages had, so every account receives the same summary, reporting counts that include the other accounts' logs. An attribute is merged instead, and the default merge strategy replaces values that differ with a wildcard, so no filter matches and the summary reaches no account.
+
+### Step 1: Put the routing key on every log \[#step1-routing-key]
+
+The routing key has to be on each log before the reducer sees it, holding one value per account. If your collectors already tag logs with the owning team or environment, use that tag. If the value is inside the message, parse it into an attribute or a tag first with the Grok parser or the JSON parser. See [_](/transforms/grok) and [_](/transforms/json-parsing).
+
+A tag and an attribute both work as the routing key. Choose one whose values are few and stable, because each value aggregates separately. Decide what happens to logs carrying no value for the key, which match no filter and so reach no account: give them a default value when you parse, or add a sink that catches them.
+
+### Step 2: Group the reducer on the routing key \[#step2-group]
+
+1. On the pipeline's **Reducer** step, click **Edit** on the **Fields** card.
+2. If the routing key is listed, set its **Behaviour** to **Match or split**.
+3. If it is not listed, enter it in the **Add field** row, set the **Behaviour** to **Match or split**, and click **Add**.
+4. Click **Save**.
+
+The **Match or split** behavior keeps a field out of aggregation, so messages whose values differ are never merged into one pattern. Enter tag keys plainly, and prefix attribute paths with `@`. An attribute is merged as well as grouped, and the default merge strategy keeps the value that every message in the group agrees on. If you set a different merge strategy for the routing attribute, check that it preserves that value rather than combining or discarding it. See [_](/transforms/reducer/configuration#attribute-configuration).
+
+### Step 3: Create a Grepr integration for each account \[#step3-integrations]
+
+Create one Grepr integration for each account you send to. An integration authenticates to a single account, so its credential is what decides where its logs land. Name each integration after its account, because that name is what you select when you add the sink. See [_](/integrations).
+
+### Step 4: Add a filtered sink for each account \[#step4-sinks]
+
+Repeat for each account:
+
+1. On the pipeline's **Sinks** step, click **Add sink**.
+2. In the **Sink** menu, select the integration for the account. Grepr fills in a **Name**, which you can change.
+3. In the **Query language** menu, select the syntax you want to write the filter in.
+4. In the **Filter Query** field, enter a query that matches only that account's logs, such as `team:platform`.
+5. Click **Add**, then save the pipeline.
+
+A sink with an empty filter forwards everything, so give each sink a filter query that matches it to one account. A sink's card reports its filter and shows **All messages** when it has none, which is how you spot one you missed. The filter runs on everything the reducer emits, so summaries, samples, passthrough messages, and exceptions all follow the same routing. To learn about the filter syntax, see [_](/queries/datadog) and [_](/queries/new-relic).
+
+## Frequently Asked Questions
+
+### Can one Grepr pipeline send logs to several accounts of the same vendor?
+
+Yes. Add one sink for each account, each pointing at that account's integration, and give each sink a filter that matches only that account's logs. Group the reducer on the same routing key the filters use, so that each summary belongs to exactly one account.
+
+### Why does the reducer need to group on the routing key?
+
+Without it, logs for different accounts aggregate together and the summary no longer identifies one account. If the key is a tag, the summary carries every value the merged messages had, so each account's filter matches it and every account receives counts that include the other accounts' logs. If the key is an attribute, the default merge strategy replaces the differing values with a wildcard, so no filter matches and the summary reaches no account.
+
+### Should I create a pipeline for each account or filter the sinks of one pipeline?
+
+Create a pipeline for each group when the groups need different reduction settings or different exceptions, or when you want them isolated. Filter the sinks of one pipeline when the groups share one reduction policy and you would rather keep a single pipeline to change.
+
+### What happens to logs that have no value for the routing key?
+
+They match no sink's filter and reach no vendor account. Give them a default value when you parse the routing key, or add a sink whose filter matches them so they land somewhere you can see.
+
+### Does a sink filter apply to summarized logs as well as raw ones?
+
+Yes. The filter runs on everything the reducer emits, so summaries, samples, passthrough messages, and exceptions all follow the same routing.

package/build/dist/docs-index/4c35d1d0-440e-45a0-a85e-2e545e644215.txt

@@ -0,0 +1,117 @@
+Connect another system's MCP server to Grepr so your AI agents can call the tools it publishes.
+
+# Configure MCP server connections with a Grepr integration
+
+An MCP integration connects Grepr to a Model Context Protocol server, or MCP server, run by another system. After you create one, you can let a Grepr AI agent call the tools that server publishes, so the agent gains capabilities, such as reading an incident, querying a dashboard, posting to a channel, or opening a pull request.
+
+> MCP integrations, along with the rest of the Grepr AI agent features, are in a closed beta. To request access, contact <support@grepr.ai>.
+
+> This page is about Grepr calling another system's MCP server. For the opposite direction, where an AI agent, such as Claude, calls Grepr's own MCP server, see [_](/apis/mcp).
+
+## Requirements
+
+To create an MCP integration, you need:
+
+* A credential for the system you are connecting. See [Create an MCP integration](#create) for where to get it.
+
+## What an agent can do through a connected server \[#server-tools]
+
+The tools an agent gains depend on the server you connect:
+
+| Type | What an agent can do with it |
+| --- | --- |
+| Datadog MCP | Read monitors, dashboards, logs, and metrics from your Datadog organization. |
+| GitHub MCP | Read and change repository content, issues, pull requests, and workflow runs. |
+| PagerDuty MCP | Read and act on incidents, services, and schedules. |
+| Slack MCP | Read and post messages in the channels the token can reach. |
+
+Each integration has a server URL you set, so you can point one at a self-hosted or regional endpoint rather than the vendor's.
+
+Don't see an MCP in the list? Send a request to <support@grepr.ai>.
+
+## Create an MCP integration \[#create]
+
+1. On the **Integrations** page, next to the **MCP Servers** section heading, click **Add new**.
+2. In the **Add MCP Server** dialog, select the server from the **Type** menu.
+3. Complete the remaining fields, which depend on the type you selected.
+4. Click **Create**.
+
+You cannot change an integration's type after you create it. You can change its other fields at any time, and each investigation picks up the change when it starts.
+
+Every type has a **Name** field, which identifies the integration when you configure an agent, and an **MCP Server URL** field. The remaining fields are the credential the server authenticates with.
+
+The credential decides what the agent can do through that MCP. Grepr passes it through as you supply it, so give the token minimal access for what the agent needs. Select the tab for the MCP you are connecting.
+
+| Field | Value |
+| --- | --- |
+| **MCP Server URL** | `https://mcp.datadoghq.com/v1/mcp`, or your regional Datadog MCP endpoint. |
+| **API Key (DD-API-KEY)** | A Datadog API key. |
+| **Application Key (DD-APPLICATION-KEY)** | A Datadog application key. |
+
+Create both keys in Datadog under **Organization Settings**. An application key carries the authorization scopes that decide what the agent can read, so scope it to the data you want the agent to reach, such as monitors, dashboards, and logs. To learn more, see [API and Application Keys](https://docs.datadoghq.com/account_management/api-app-keys/) and [Authorization Scopes](https://docs.datadoghq.com/api/latest/scopes/) in the Datadog documentation.
+
+If you already use Datadog as a Grepr source or sink, this is a separate integration. Reusing the same keys is fine. See [_](/integrations/datadog).
+
+| Field | Value |
+| --- | --- |
+| **MCP Server URL** | `https://api.githubcopilot.com/mcp/`, or your GitHub Enterprise MCP endpoint. |
+| **Personal access token** | A GitHub personal access token. |
+
+Create the token in GitHub under **Settings** > **Developer settings** > **Personal access tokens**. A fine-grained token is the better choice, because you can limit it to the repositories the agent works in.
+
+Grant the token access to the repository content, issues, pull requests, and workflow runs the agent needs. An agent that only reads code needs read access alone, and an agent that opens pull requests needs write access to contents and pull requests. To learn more, see [Managing your personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-secure/managing-your-personal-access-tokens) in the GitHub documentation.
+
+| Field | Value |
+| --- | --- |
+| **MCP Server URL** | `https://mcp.pagerduty.com/mcp`, or your PagerDuty MCP endpoint. |
+| **Account URL** | Your PagerDuty account URL, such as `https://<your-org>.pagerduty.com`. Optional. |
+| **API Key** | A PagerDuty API key. |
+
+Create the key in PagerDuty under **Integrations** > **API Access Keys**. A read-only key lets an agent read incidents, services, and schedules, and a full-access key also lets it acknowledge or resolve incidents, so choose the one that matches what you want the agent to do. To learn more, see [API Access Keys](https://support.pagerduty.com/main/docs/api-access-keys) in the PagerDuty documentation.
+
+Grepr uses the **Account URL** to build links back to incidents in the actions an agent records, so set it if you want those links to resolve.
+
+| Field | Value |
+| --- | --- |
+| **MCP Server URL** | `https://mcp.slack.com/mcp`, or your Slack MCP endpoint. |
+| **User token** | A Slack user token, which begins with `xoxp-`. |
+
+Create a Slack app in your workspace, add the user token scopes the agent needs, then install the app to get the token. Grant `channels:read` and `channels:history` for an agent that reads channels, and add `chat:write` for one that posts. The agent reaches only the channels the token's user is in, so invite that user to the channels you want covered. To learn more, see [Access tokens](https://docs.slack.dev/authentication/tokens) in the Slack documentation.
+
+## Choose which tools an agent can call \[#allowed-tools]
+
+Creating an integration does not give any agent access to it. You enable an integration on each agent, and you choose which of the server's tools that agent can call. Two agents can therefore share one integration with different tool allowances.
+
+The tool allowance lives on the agent, not on the integration. To set it, go to the agent's **Capabilities** step, find the integration in the **MCP integrations** table, and edit its allowed tools. Grepr reads the tool list from the server, marks each tool as read only or writing, and lets you allow all tools or only the ones you select. To learn more, see [_](/ai-agents/capabilities#mcp-integrations).
+
+An agent can enable at most one GitHub MCP integration. The agent's `github_code` tool also requires an enabled GitHub MCP integration, because that is how it reaches source code.
+
+## Grant team access \[#team-access]
+
+When you have teams in your Grepr organization, you can grant access to the integration to one or more of those teams. To configure team access when you create or edit an integration:
+
+1. In the **Grant Team Access** section, click the plus sign icon (+).
+
+2. Select the team or teams that should be granted access to the integration.
+
+3. Click **Create**.
+
+To learn more, see [Manage teams in the Grepr platform](/admin/manage-teams) and [Permissions in the Grepr platform](/grepr-platform/permissions).
+
+## Frequently Asked Questions
+
+### Which MCP servers can Grepr AI agents connect to?
+
+You set each integration's server URL, so you can point one at a self-hosted or regional endpoint. Grepr adds integrations continuously, so contact support\@grepr.ai to get an agent connected to the server you use.
+
+### How do I limit which MCP tools a Grepr AI agent can call?
+
+The allowance is set on the agent, not on the integration. On the agent's Capabilities step, find the integration in the MCP integrations table and either allow all of the server's tools or select individual tools. Grepr reads the tool list from the server and marks each tool as read only or writing.
+
+### What is the difference between an MCP integration and the Grepr MCP server?
+
+An MCP integration lets a Grepr AI agent call another system's MCP server. The Grepr MCP server is the reverse: it lets an AI assistant such as Claude or Claude Code call Grepr to list pipelines, query logs, and propose pipeline changes.
+
+### How do I change an MCP integration after creating it?
+
+Edit it from the three-dot menu on the integration card. Investigations that start after the change use the new settings, and one already running keeps the settings it started with. An integration's type is fixed when you create it, so to move to a different server type, create a new integration.

package/build/dist/docs-index/{fa209892-1df2-42e3-a129-07939370f0a7.txt → 57c18b26-2872-419f-a362-0c035cf5159d.txt}

@@ -4,7 +4,7 @@
 
 **Operation ID**: `getIntegrationExceptionImpacts`
 **Summary**: Get integration exception impacts for a pipeline
-Returns the per-exception impact percentages the runtime auto-sync threshold filter would compare against for this pipeline/integration pair. The pipeline's sink dataset scopes the lookup; exceptions without an estimation row are absent from the response.
+Returns the per-exception impact percentages the runtime auto-sync threshold filter would compare against for this pipeline/integration pair, each with the time that estimate was measured. The pipeline's sink dataset scopes the lookup; exceptions without an estimation row are absent from the response rather than reported as zero.
 
 ## Tags
 - Pipeline Exceptions

package/build/dist/docs-index/58616cf1-ab6b-4516-a955-98117ec38d41.txt

@@ -0,0 +1,136 @@
+Control what a Grepr AI agent can reach with a service account, tools, skills, and MCP integrations, and whether its pipeline changes need approval.
+
+# Control what an AI agent can do
+
+An agent's reach is bounded in layers, and a capability has to be allowed by every layer to work:
+
+1. The **service account** the agent acts as. Its roles are the outer boundary and cap everything the agent can reach in Grepr.
+2. The **tools and skills** you enable. These narrow the agent to specific operations within what the service account permits.
+3. The **MCP integrations** you enable, and the tools you allow on each. These decide what the agent can reach in other systems.
+
+A fourth setting, the change approval mode, decides whether the agent can make automatic changes to your pipeline.
+
+These settings are on the agent's **Capabilities** step, and on the matching step of the create wizard.
+
+## Choose the service account an agent acts as \[#service-account]
+
+Every call an agent makes to Grepr authenticates as the service account you select in the **Service account** field. The service account's roles decide which pipelines, datasets, and integrations the agent can read and write to.
+
+The service account is the boundary that holds even if a tool grant is over-permissive. An agent with the pipeline editing tool but a service account that can only view jobs cannot change a pipeline. Grant the narrowest role that lets the agent finish its job. To create one, see [_](/admin/service-accounts).
+
+If the **Service account** menu is empty, create a service account before you continue.
+
+## What every agent can already do \[#sandbox-baseline]
+
+Each investigation runs in its own sandbox, and inside that sandbox an agent can:
+
+* Run shell commands.
+* Run Python for local analysis and scripting.
+* Query files it downloaded with DuckDB.
+* Read, create, and edit files in its own workspace.
+
+These are part of the sandbox and cannot be turned off. They act only on the sandbox, which is discarded when the investigation ends, so they do not reach your data or your pipelines. Everything that does reach Grepr is granted separately, as described next.
+
+## Grant access to Grepr with tools and skills \[#grepr-access]
+
+The **Grepr access** section is where you decide what the agent can do. You grant access in two ways, and most agents use both:
+
+* Enable a skill, which gives the agent guidance for a task and, when the skill needs them, the tools that task requires.
+* Pin an individual tool, which grants that tool with no accompanying guidance.
+
+Prefer skills. A skill tells the agent how to use what it grants, so an agent with a skill usually needs fewer turns than one holding the bare tool. Pin a tool when you want a capability that no skill attached covers.
+
+### Abilities and reference skills \[#skill-kinds]
+
+Skills are grouped by whether enabling one is a permission decision:
+
+* **Abilities** carry tools. Enabling one grants the agent the operations that skill needs, so treat it as granting access.
+* **Reference** skills carry only knowledge. Enabling one changes what the agent knows, never what it can do, so it is safe to enable freely.
+
+To read what a skill covers and what it grants before you enable it, open its detail from the selector. To learn what skills exist and how to write your own, see [_](/ai-agents/skills).
+
+### How much a skill grants \[#grant-scope]
+
+How wide a skill's grant is depends on its scope, and the difference matters when you are reasoning about least privilege:
+
+* A **platform skill**, which Grepr maintains, grants exactly the operations its definition lists. A skill that needs only to preview a pipeline change gets the preview operation and not the one that applies it.
+* An **organization skill**, which you create, grants the whole *tool family* behind each tool you approve on it, meaning every operation that tool covers rather than only the ones the skill uses. Approving the pipeline editing tool on your own skill grants everything that tool covers, not only the part your instructions use.
+
+So an organization skill is as broad as the tools you approve on it. To keep a grant narrow, approve fewer tools on the skill rather than relying on the skill's instructions to limit the agent.
+
+Enabling a tool directly always grants its whole family, the same way an organization skill does.
+
+### Tool reference \[#tool-table]
+
+| Tool | What it lets the agent do |
+| --- | --- |
+| `query_logs` | Query the logs in your Grepr datasets. |
+| `get_pipeline` | Read the configuration of your pipelines and templates. |
+| `edit_pipeline` | Propose a change to a pipeline's configuration, and preview a change before proposing it. |
+| `grok` | Build and test Grok parsers. |
+| `datasets` | List, read, and manage your Grepr datasets. |
+| `integrations` | List and read your Grepr integrations. |
+| `docs` | Search the Grepr documentation and validate SQL. |
+| `backfill` | Replay logs from the data lake to a vendor destination. |
+| `investigations` | Read agent configuration, past investigations, and their transcripts. |
+| `github_code` | Clone, edit, and publish source repositories. Requires an enabled GitHub MCP integration. |
+
+An agent's pipeline changes are scoped to a pipeline's Grok parsers and its SQL transforms, so granting the pipeline editing tool keeps the rest of the pipeline configuration out of the agent's reach. Both are add-only. An agent can add a Grok rule or add a SQL transform, and it cannot change or remove one that is already there, so its proposals accumulate alongside your configuration rather than rewriting it.
+
+A SQL transform an agent adds is a filter and nothing further. It reads the pipeline's logs and selects them unchanged against a single condition, so it cannot join, aggregate, read a dataset, register a function, or keep state. It routes the events it matches to the agent signal sink, which you configure yourself when you set the pipeline up. An agent can add routes to that sink, and it cannot create, change, or remove the sink. That limit is on what an agent adds by itself. A SQL output you route to the agent signal sink yourself carries no such restriction, so you can build the event an agent receives however you need. See [_](/ai-agents/subscriptions#agent-signal-sink).
+
+The tools an agent uses to record and search its memory are not in this list. They are granted by the agent's memory settings instead, so that turning memory on is the single decision that controls them. See [_](/ai-agents/memory).
+
+## Let an agent call an MCP server's tools \[#mcp-integrations]
+
+The **MCP integrations** section lists the MCP integrations in your organization and which of their tools the agent can use. Two agents can share one integration with different tool access enabled.
+
+Edit the integration's allowed tools and choose either every tool the server publishes or only the ones you select. Grepr reads the tool list from the server and marks each tool as read only or writing; for example, you can allow an agent to read incidents without allowing it to change them.
+
+Allowing every tool means the agent gains any tool the server adds later, which is convenient for a read-only server and worth avoiding for one that can make changes. Selecting individual tools keeps the enabled tools fixed until it is manually changed.
+
+Two rules apply to GitHub:
+
+* An agent can enable at most one GitHub MCP integration.
+* The `github_code` tool needs an enabled GitHub MCP integration, because that integration is how it reaches source code.
+
+To create an integration, see [_](/integrations/mcp).
+
+## Decide whether pipeline changes need approval \[#change-approval]
+
+An agent that decides a pipeline needs a configuration update does not edit it directly. It submits the change, and the **Pipeline changes** setting decides what happens next:
+
+| Mode | What happens when the agent proposes a change |
+| --- | --- |
+| **Require human approval** | Grepr records the change as a suggestion on the pipeline. Nothing changes until you review and apply it. |
+| **Auto-apply** | Grepr verifies the change and applies it. A running pipeline restarts to pick it up. No person is involved. |
+
+**Require human approval** is the default, and it is the right setting while you are learning how an agent behaves. Auto-apply an agent's changes only after its suggestions have consistently been ones you would have made yourself.
+
+Grepr enforces the mode at the operation level, so while an agent can always preview pipeline changes, it cannot bypass **Require human approval** to apply them.
+
+A change that lands on a running pipeline restarts it, which interrupts processing briefly.
+
+To review suggestions, see [_](/ai-agents/investigations#suggestions).
+
+## Frequently Asked Questions
+
+### How do I limit what a Grepr AI agent can reach?
+
+Reach is bounded in layers. The service account the agent acts as is the outer boundary and caps everything it can reach in Grepr. Within that, the tools and skills you enable narrow it to specific operations, and the MCP integrations you enable with their allowed tools decide what it can reach in other systems.
+
+### What can a Grepr AI agent do without any tools enabled?
+
+Inside its own sandbox it can always run shell commands and Python, query downloaded files with DuckDB, and read and write files in its workspace. These act only on the sandbox, which is discarded when the investigation ends, and they do not reach your data or pipelines.
+
+### What is the difference between an ability and a reference skill?
+
+An ability carries tools, so enabling one grants the agent the operations that skill needs and is a permission decision. A reference skill carries only knowledge, so enabling one changes what the agent knows but never what it can do.
+
+### Do platform skills and organization skills grant the same access?
+
+No. A platform skill grants exactly the operations its definition lists, which can be narrower than a whole tool. An organization skill grants the whole tool family behind each tool you approve on it, so keep its grant narrow by approving fewer tools.
+
+### Can a Grepr AI agent change my pipeline without approval?
+
+Only when you set its change approval mode to Auto-apply. The default, Require human approval, records every proposed change as a suggestion for you to review. Grepr enforces the mode server-side, so an agent has no route around it whatever its instructions say.

package/build/dist/docs-index/{4da732d4-1309-47b4-8ddf-ea25f2cac73b.txt → 5c2260ca-8d9b-4ff2-a09f-66a415f7b544.txt}

@@ -38,6 +38,14 @@ API key is invalid
 
 No such webhook integration
 
+### 409
+
+The integration has no live target agent to start
+
 ### 413
 
 Body exceeds the size limit
+
+### 503
+
+At least one target agent could not be started for a transient reason; retry

package/build/dist/docs-index/622df8d9-d453-40b7-8dad-fcf34dbfc530.txt

@@ -0,0 +1,19 @@
+# PreviewAppKeyScopesRequest
+
+Unsaved changes to check Datadog authorization scopes against
+
+**Type**: `object`
+
+## Properties
+
+- name: apiKey (optional)
+  type: string
+  description: API key to probe with instead of the stored one
+
+- name: appKey (optional)
+  type: string
+  description: Application key to check instead of the stored one
+
+- name: site (optional)
+  type: string
+  description: Site to probe instead of the stored one

package/build/dist/docs-index/69875854-9530-48c5-984a-890f7233f7b1.txt

@@ -0,0 +1,30 @@
+# Get parsed-query import state
+
+**GET** `/v1/integrations/{integrationId}/parsed-queries/import`
+
+**Operation ID**: `getParsedQueryImportStatus`
+**Summary**: Get parsed-query import state
+Says whether this vendor's parsed queries can be imported, whether the credential the import needs is saved, whether an import is already under way, and which integrations an import covers. Poll this while an import is running; what it imported is reported in the integration's activity log.
+
+## Tags
+- Integrations
+## Parameters
+
+- **integrationId** (required) - path
+  - Integration id
+  - Type: string
+
+## Responses
+
+### 200
+
+State retrieved
+
+- **Content-Type**: `application/json` / `ParsedQueryImportStatus`
+### 401
+
+Unauthorized
+
+### 404
+
+Not Found - Integration not found.