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 lets compatible AI clients work with your PR data directly. You can explore coverage, inspect outlets and project configuration, and analyze AI visibility data without exporting it first, and you can add and maintain coverage without leaving the client.

Reading is the default. Writing is opt-in: a client only gets it if it asks for a write permission such as clippings:write or prompts:write and you approve it on the consent screen, and deleting anything always asks you to confirm 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.

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:

Choose the organization the client may access. A connection always covers exactly one organization; to switch, disconnect and connect again.
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.
Approve. The client receives exactly the permissions shown on the consent screen. Write permissions are highlighted there, and are never included unless the client asked for them.

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 and can disconnect any of them immediately.

Claude (web)

Open Settings, then Connectors, and choose "Add custom connector".
Enter https://api.aclipp.com/mcp as the URL and confirm.
Click Connect and complete the aclipp sign-in in the browser window.
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:

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.
Create a connector with the MCP server URL https://api.aclipp.com/mcp and OAuth as the authentication method.
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 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 and project configuration.
`projects:write`	Create and update project tags and custom metrics.
`prompts:read`	AI visibility prompts and prompt topics.
`prompts:write`	Create and update prompts.
`clippings:read`	Filtered clipping lists and complete clipping details.
`clippings:write`	Create and update clippings.
`outlets:read`	Outlet lists and complete outlet details.
`reports:read`	Report lists and complete report details.
`reports:write`	Create, update, and delete reports.
`dashboards:read`	Dashboard lists and complete dashboard details.
`dashboards:write`	Create, update, and delete dashboards.
`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.

Some tools need both the write and the read scope for their resource, because they read the record to do their job. delete_prompt needs prompts:write and prompts:read, and the report and dashboard update and replace tools need the read scope to base the change on the document's current version.

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`
`create_tag` — Create tags	Creates one or more tags in a project (up to 25 per call).	`projects:write`
`update_tag` — Update tag	Changes one existing tag, including its name, description, or tag group.	`projects:write`
`create_custom_metric` — Create custom metrics	Creates one or more project-defined clipping metrics (up to 25 per call).	`projects:write`
`update_custom_metric` — Update custom metric	Changes one existing project-defined clipping metric.	`projects:write`
`list_prompts` — List AI visibility prompts	Lists tracked prompts with their location, status, and topic.	`prompts:read`
`list_prompt_topics` — List prompt topics	Lists prompt topics for filtering and grouping AI visibility data.	`prompts:read`
`create_prompt` — Create prompts	Adds one or more AI visibility prompts to a project (up to 25 per call). Results appear over following runs, not immediately.	`prompts:write`
`update_prompt` — Update prompt	Changes an existing prompt. New wording applies from the next run onward and does not rewrite results already collected.	`prompts:write`
`delete_prompt` — Delete prompt	Stops a prompt being asked, after you confirm. Collected results stay in your history.	`prompts:write`, `prompts:read`
`list_clippings` — List clippings	Lists compact clipping records, filtered with a boolean filter expression over date, channel, tag, outlet, country, sentiment, and more.	`clippings:read`
`get_clipping` — Get clipping	Returns the full details for one clipping.	`clippings:read`
`clip_url` — Clip a URL	Adds coverage from a link and lets the processing pipeline derive the title, publication date, outlet, sentiment and metrics. The preferred way to add coverage.	`clippings:write`
`create_clipping` — Create clipping	Records coverage that has no fetchable link, such as print or broadcast. Stores exactly the fields supplied and infers nothing.	`clippings:write`
`update_clipping` — Update clipping	Changes fields on an existing clipping. An outlet that does not exist is rejected.	`clippings:write`
`get_report` — Get report	Returns one report with its complete ordered content blocks.	`reports:read`
`create_report` — Create reports	Creates one or more reports in a project (up to 25 per call), optionally laid out with content blocks in the same call. Always private.	`reports:write`
`update_report` — Update report settings	Changes a report's name, theme color, sharing access level, filter or sorting. Its content blocks are never touched.	`reports:write`, `reports:read`
`replace_report_blocks` — Replace report blocks	Sets a report's complete ordered content. Replaces the whole collection, so any block left out is removed.	`reports:write`, `reports:read`
`get_dashboard` — Get dashboard	Returns one dashboard with its complete ordered charts.	`dashboards:read`
`create_dashboard` — Create dashboards	Creates one or more dashboards in a project (up to 25 per call), optionally laid out with charts in the same call. Always private.	`dashboards:write`
`update_dashboard` — Update dashboard settings	Changes a dashboard's name, sharing access level, filter, comparison period, or whether viewers may filter it. Its charts are never touched.	`dashboards:write`, `dashboards:read`
`replace_dashboard_charts` — Replace charts	Sets a dashboard's complete ordered chart list. Replaces the whole collection, so any chart left out is removed.	`dashboards:write`, `dashboards: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`
`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_scalar` — Query one value	Returns a single total for one metric, optionally against a comparison period.	`analytics:read`
`query_analytics_scalars` — Query several values	Returns several independent totals in one call, one per requested metric.	`analytics:read`
`query_analytics_series` — Query a time series	Returns per-day values for one or more metrics over a date range.	`analytics:read`
`query_analytics_breakdown` — Query a breakdown	Splits one metric by a dimension (brand, provider, topic, prompt, country, channel, outlet, tag, sentiment) and ranks the groups.	`analytics:read`
`query_analytics_table` — Query a table	Splits several metrics by one dimension and returns a row per group with a column per metric.	`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, and a tool only appears when the connection holds every scope that tool needs. Some tools need more than one: delete_prompt also reads the record to describe it in the confirmation prompt, and the report and dashboard update and replace tools read the document to base the change on its current version.

OAuth connections receive the supported scopes requested by the client; if the client requests no scopes, aclipp grants the full supported read set and no write access. For API keys, update or replace the key with the scopes the tool needs, then reconnect the server so the client refreshes its tool list.

A tool can also appear and still be refused. Tools are offered on scopes alone, but an OAuth connection acts with your role in the workspace, and that role is rechecked on every call. An editor, for example, may create dashboards but not change them, so update_dashboard is offered and then answers that the change is not permitted. API keys are not bound by a role this way.

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

Connect AI tools to aclipp with MCP

Supported clients

Before you start

Sign in with aclipp (OAuth)

Claude (web)

Claude Desktop

ChatGPT

Create an API key

Claude Code

Cursor

Available MCP tools

Try your first analysis

Troubleshooting

Connection failed

Authentication failed

A tool is missing

The client shows an outdated tool list

Remove the connection

Keep your API key safe

Search the API reference