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.

## Use Grepr skills through the MCP server \[#skills]

The MCP server also provides *skills*: instructions that teach an AI assistant how to work with Grepr efficiently. The server lists each skill in the instructions it sends when your client connects, and serves each skill's files as MCP resources at `skill://<skill-name>/SKILL.md`. MCP clients that read resources, such as Claude Code, load a skill when your request matches it.

The server provides the following skills:

* `cli`: Installs, configures, and signs in to the Grepr CLI, and points to the other Grepr skills.
* `query`: Queries logs and spans with the Grepr CLI, scoped so that each query reads as little data as possible.
* `query-predicate`: Translates a request into a Grepr query predicate.
* `recover-reduced-logs`: Explains the summary logs that Grepr sends to your observability vendor in place of repeated logs, and finds the original logs behind a summary in the Grepr data lake.
* `backfill-logs`: Sends original logs from the Grepr data lake to your observability vendor.

When your AI assistant can run shell commands, the skills use the Grepr CLI instead of the MCP tools, because the CLI writes results to a file and has no page limit. To install the CLI, see [Grepr CLI](/cli). The [coding assistant plugins](/cli#agent-skills) include these skills and the rest of the Grepr skills.

## Frequently Asked Questions

### Does the Grepr MCP server provide skills?

Yes. The server lists its skills in the instructions it sends when a client connects and serves each skill as an MCP resource at skill://\<skill-name>/SKILL.md. The skills cover setting up the Grepr CLI, querying logs and spans, building query predicates, recovering the original logs behind a Grepr summary, and backfilling logs to your observability vendor.

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