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, authors and project configuration, and analyze AI visibility data without exporting it first, and you can set up projects and the competitors they are measured against, then add and maintain coverage, outlets and authors, 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. Deleting a prompt asks you to confirm first. Replacing report blocks or dashboard charts removes anything omitted from the replacement.

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, and they differ in one way worth knowing: an API key always covers exactly one organization, while signing in with aclipp can cover several.

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 organizations the client may access. If you belong to only one, it is used and there is nothing to pick. If you belong to several, select every organization this connection should cover, and optionally tick Include future organizations so a workspace you are invited to afterwards is covered without reconnecting. Tools then take an optional organizationId; omit it and the call acts in your default organization.
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. Expand Show permissions to see the requested actions for each area. The client receives exactly those permissions; write access is included only if the client requested it.

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, competitors, and project configuration.
`projects:write`	Create projects and competitors; update competitors, 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.
`outlets:write`	Create, update, and delete outlets.
`authors:read`	Author lists and complete author profiles.
`authors:write`	Create, update, and delete authors.
`alerts:read`	Alert configurations and their filters.
`alerts:write`	Create and update alerts. Deletion needs an API key.
`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.

outlets:write and authors:write cover creating, editing and deleting, over an API key and over Sign in with aclipp alike. Deletion is still held to your own role: an editor may delete only the outlets and authors they created.

alerts:write is narrower: it creates and updates alerts over an API key and over Sign in with aclipp alike, but deleting one works only with an API key. An alert that is deleted simply stops sending, and nobody sees that happen, so removing one stays with a credential a person configured themselves. Disable the alert instead to stop its mails reversibly.

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
`me` — Inspect this connection	Reports the workspace, permissions, and project restrictions of the current connection.	`projects:read`
`list_organizations` — List organizations	Lists the organizations this connection may act in. Every other tool takes an optional `organizationId` from here.	`projects:read`
`list_projects` — List projects	Lists the projects visible to the connection and returns their IDs.	`projects:read`
`get_project_config` — Get project configuration	Returns a project's tracked brand IDs, tags, tag groups, and custom metric definitions.	`projects:read`
`create_project` — Create project	Creates a project and picks the licenses it holds. AI Visibility is the one competitors and prompts need.	`projects:write`
`list_competitors` — List competitors	Lists the competitor brands a project tracks, with the name, aliases, and domains each one is matched by.	`projects:read`
`create_competitor` — Create competitors	Adds one or more competitor brands to an AI Visibility project (up to 25 per call). Answers and pages already collected are re-analyzed, so past mentions appear once that pass finishes.	`projects:write`
`update_competitor` — Update competitor	Changes one competitor's name or how it is matched. Aliases and domains are replaced as whole lists, not added to, and changing them re-analyzes the project's history.	`projects:write`
`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 settings	Changes a prompt's location, status, frequency, or topic. Wording stays fixed so historical results remain tied to the same question.	`prompts:write`
`delete_prompt` — Delete prompt	Stops a prompt being asked, after you confirm. Collected results stay in your history.	`prompts:write`, `prompts:read`
`create_prompt_topic` — Create prompt topics	Creates one or more topics for grouping prompts in an AI visibility project (up to 25 per call). Topic IDs work as filters and as the `topic` analytics dimension.	`prompts:write`
`update_prompt_topic` — Rename prompt topic	Renames one existing prompt topic. The prompts grouped under it and the history reported against it are untouched.	`prompts:write`
`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`
`list_reports` — List reports	Lists the reports in a project or across the workspace with their IDs, settings and sharing URL. Content blocks are not included.	`reports:read`
`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`
`list_dashboards` — List dashboards	Lists the dashboards in a project or across the workspace with their IDs, settings and sharing URL. Charts are not included.	`dashboards: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`
`update_outlet` — Update outlet	Corrects or enriches one outlet's name, reach figures, country, language, and channel-specific profile. The logo cannot be set from here.	`outlets:write`
`list_alerts` — List alerts	Lists a project's alerts with their filters, recipients, trigger and enabled state.	`alerts:read`
`create_alert` — Create alerts	Creates one or more alerts in a project (up to 25 per call). Each mails its recipients when newly processed coverage matches its filter.	`alerts:write`
`update_alert` — Update alert	Changes an alert's name, filter, recipients, trigger or enabled state. Filters and recipients are replaced whole, not merged.	`alerts:write`
`list_authors` — List authors	Lists the journalists and creators behind the coverage, with clipping counts, outlets, and first and last publication dates.	`authors:read`
`get_author` — Get author	Returns one author with their profiles, every outlet they published in, and their most recent clippings.	`authors:read`
`update_author` — Update author	Corrects an author's name and replaces the profiles and outlet links that are maintained by hand.	`authors:write`
`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`
`list_geo_search_queries` — List search queries	Lists the web searches AI providers ran while answering a project's prompts, with how often each was run.	`ai-visibility:read`
`search_geo_domains` — Search source domains	Searches the domains AI answers cite, with citation counts and the tracked brands each page mentions.	`ai-visibility:read`
`search_geo_urls` — Search source URLs	Searches the individual pages AI answers cite, with citation counts and the tracked brands each page mentions.	`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