# Connect AI tools to aclipp with MCP

Connect Claude, ChatGPT, and developer tools to the hosted aclipp MCP server, and explore every available tool.

The aclipp MCP server gives compatible AI clients read-only access to your PR data. You can explore coverage, inspect outlets and project configuration, and analyze AI visibility data without exporting it first.

All clients connect to the hosted endpoint at `https://api.aclipp.com/mcp`. You do not need to run an aclipp server or a local development process. There are two ways to authenticate:

- **Sign in with aclipp (OAuth):** for interactive clients such as Claude and ChatGPT. No API key needed; you approve the connection in your browser.
- **API key:** for developer tools such as Claude Code and Cursor, or wherever you prefer a long-lived credential.

## Supported clients

| Client         | Status                     | Authentication                   |
| -------------- | -------------------------- | -------------------------------- |
| Claude (web)   | Available                  | Sign in with aclipp              |
| Claude Desktop | Available                  | Sign in with aclipp              |
| ChatGPT        | Available (developer mode) | Sign in with aclipp              |
| Claude Code    | Available                  | aclipp API key in an HTTP header |
| Cursor         | Available                  | aclipp API key in `mcp.json`     |

## Before you start

You need an aclipp workspace with API access enabled. For Claude and ChatGPT, your normal aclipp login is all it takes. For Claude Code and Cursor you also need an aclipp API key with the read scopes your AI client should use.

## Sign in with aclipp (OAuth)

When you add `https://api.aclipp.com/mcp` as a connector, the client discovers the aclipp sign-in flow on its own and opens your browser. You sign in with your aclipp account, then approve the connection:

1. **Choose the organization** the client may access. A connection always covers exactly one organization; to switch, disconnect and connect again.
2. **Choose the projects.** All projects are included by default, which also covers projects created later. Narrow the selection if the client should only see specific projects.
3. **Approve.** The client receives read-only access matching the permissions shown on the consent screen.

Connections are personal: they act on your behalf and end when you leave the organization. Workspace admins see every connection under [Settings, Developers, Connected apps](https://app.aclipp.com/settings/api/connected-apps) and can disconnect any of them immediately.

### Claude (web)

1. Open Settings, then Connectors, and choose "Add custom connector".
2. Enter `https://api.aclipp.com/mcp` as the URL and confirm.
3. Click Connect and complete the aclipp sign-in in the browser window.
4. In a chat, enable the aclipp connector in the tools menu. The aclipp tools are now available.

Custom connectors require a paid Claude plan. On Team and Enterprise plans an admin may need to enable them first.

### Claude Desktop

Claude Desktop uses the same connector settings as Claude on the web: add `https://api.aclipp.com/mcp` under Settings, Connectors, and complete the browser sign-in.

### ChatGPT

ChatGPT connects through developer mode:

1. Open Settings, then Apps & Connectors, then Advanced, and enable developer mode. This requires a paid plan; on Team and Enterprise plans an admin must allow it.
2. Create a connector with the MCP server URL `https://api.aclipp.com/mcp` and OAuth as the authentication method.
3. Complete the aclipp sign-in, then enable the connector in a chat.

ChatGPT snapshots the tool definitions when a connector is approved. Reconnect the connector after aclipp releases new tools so ChatGPT refreshes its list.

## Create an API key

For Claude Code and Cursor, open [workspace API settings](https://app.aclipp.com/settings/api) and create a key for your AI client. The full key is shown only once, so copy it before closing the dialog.

Grant only the scopes you need:

| Scope                | What it enables                                              |
| -------------------- | ------------------------------------------------------------ |
| `projects:read`      | Projects, project configuration, prompts, and prompt topics. |
| `clippings:read`     | Filtered clipping lists and complete clipping details.       |
| `outlets:read`       | Outlet lists and complete outlet details.                    |
| `analytics:read`     | Aggregated clipping and AI-visibility analytics.             |
| `ai-visibility:read` | AI visibility chats, metrics, cited domains, and cited URLs. |

The scopes determine which tools the client sees. You can also restrict the key to specific projects.

### Claude Code

Run this command in your terminal and replace the example key with your new key:

```bash
claude mcp add \
  --transport http \
  --scope user \
  --header "Authorization: Bearer aclipp_live_..." \
  aclipp https://api.aclipp.com/mcp
```

The `user` scope makes the connection available in every Claude Code project on your computer.

Start Claude Code and enter:

```text
/mcp
```

The `aclipp` server should be connected and show its available tools. You can also check the connection from a terminal:

```bash
claude mcp list
```

### Cursor

Open the global MCP configuration at `~/.cursor/mcp.json`, or create `.cursor/mcp.json` when the connection should only be available in one project. Add:

```json
{
  "mcpServers": {
    "aclipp": {
      "url": "https://api.aclipp.com/mcp",
      "headers": {
        "Authorization": "Bearer aclipp_live_..."
      }
    }
  }
}
```

Replace the example key, save the file, and open Cursor's MCP settings. The `aclipp` server should become available with its permitted tools. Restart Cursor or toggle the server off and on if it does not reconnect immediately.

Do not commit a project-level `.cursor/mcp.json` containing an API key. Prefer the global configuration for a personal connection.

## Available MCP tools

The server only registers tools permitted by the connection's scopes. This is the complete current tool catalog:

| Tool                                                | What it does                                                                                                                             | Required scope       |
| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| `list_projects` — List projects                     | Lists the projects visible to the connection and returns their IDs.                                                                      | `projects:read`      |
| `get_project_config` — Get project configuration    | Returns tags, tag groups, and custom metric definitions for a project.                                                                   | `projects:read`      |
| `list_prompts` — List AI visibility prompts         | Lists tracked prompts with their location, status, and topic.                                                                            | `projects:read`      |
| `list_prompt_topics` — List prompt topics           | Lists prompt topics for filtering and grouping AI visibility data.                                                                       | `projects:read`      |
| `list_clippings` — List clippings                   | Lists compact clipping records with date, channel, tag, outlet, country, sentiment, and search filters.                                  | `clippings:read`     |
| `get_clipping` — Get clipping                       | Returns the full details for one clipping.                                                                                               | `clippings:read`     |
| `list_outlets` — List outlets                       | Lists media outlets with search, channel, project, and clipping-count context.                                                           | `outlets:read`       |
| `get_outlet` — Get outlet                           | Returns one outlet with its full channel-specific profile and reach data.                                                                | `outlets:read`       |
| `list_geo_chats` — List AI visibility chats         | Lists AI visibility runs for a project, date range, provider, country, prompt, or topic.                                                 | `ai-visibility:read` |
| `get_geo_chat` — Get AI visibility chat             | Returns the complete detail for one AI visibility run.                                                                                   | `ai-visibility:read` |
| `get_geo_metrics` — Query AI visibility metrics     | Returns visibility, share of voice, position, sentiment, and mention metrics with optional grouping and time buckets.                    | `ai-visibility:read` |
| `search_geo_sources` — Search AI visibility sources | Searches source domains and URLs cited in AI visibility runs.                                                                            | `ai-visibility:read` |
| `get_geo_source` — Get AI visibility source         | Returns the details for one cited source domain or URL.                                                                                  | `ai-visibility:read` |
| `get_analytics_catalog` — Get analytics catalog     | Lists the metrics, shapes, dimensions, formats, and aggregations currently available for a project.                                      | `analytics:read`     |
| `query_analytics` — Query analytics                 | Returns scalar, time-series, breakdown, or table analytics for clipping and AI-visibility data, including clipping sentiment breakdowns. | `analytics:read`     |

Keep this table in sync when MCP tools or their required scopes change.

## Try your first analysis

Start by letting the client discover your project and its configuration:

```text
Use aclipp to list my projects. For the relevant project, inspect its
configuration and summarize this year's coverage by channel, country,
sentiment, and outlet. Highlight the strongest coverage and any notable gaps.
```

The client can resolve tag IDs through the project configuration and should use the analytics catalog for valid metric, shape, dimension, and aggregation combinations. Series, breakdown, and table queries require a date range of no more than 366 days. Row-producing queries are bounded and tell the client when a result was truncated.

For example:

```text
Compare our coverage in Germany and Austria during the last quarter. Break it
down by channel and sentiment, list the top outlets, and cite the clippings
behind any important conclusion.
```

## Troubleshooting

### Connection failed

Confirm that the configured URL is `https://api.aclipp.com/mcp`. In Claude Code, run `claude mcp list`. In Cursor, open the MCP settings and inspect the server status.

### Authentication failed

For OAuth connections, disconnect the connector in your client and connect again; the browser sign-in issues a fresh grant. This is also needed after an admin disconnected the connection or after you left the organization. For API keys, create a new key if the configured key was revoked, copied incorrectly, or is no longer available. aclipp API keys use the `aclipp_live_...` format, and the header value must start with `Bearer `.

### A tool is missing

Tools are registered according to the connection's scopes. OAuth connections receive all read scopes automatically. For API keys, update or replace the key with the required read scope, then reconnect the server so the client refreshes its tool list.

### The client shows an outdated tool list

Reconnect the `aclipp` server or start a new client session. ChatGPT snapshots tool definitions when a connector is approved, so reconnect it there as well.

### Remove the connection

For Claude and ChatGPT, disconnect the connector in the client's settings. Workspace admins can also disconnect any OAuth connection under [Settings, Developers, Connected apps](https://app.aclipp.com/settings/api/connected-apps), which cuts off access within a minute.

Remove the user-scoped Claude Code server with:

```bash
claude mcp remove aclipp --scope user
```

For Cursor, remove the `aclipp` entry from `mcp.json`. Revoke the API key in [workspace API settings](https://app.aclipp.com/settings/api) when it is no longer needed.

## Keep your API key safe

The API key is stored in your client's private configuration. Never commit it or paste it into a chat, issue, screenshot, or shared terminal transcript. Use a separate, minimally scoped key for each client so you can revoke one connection without affecting another.