<!-- The markdown copy of https://oppalerts.com/docs/getting-started/use-oppalerts-in-your-ai-agent . All pages: https://oppalerts.com/docs/llms.txt -->

[Documentation](https://oppalerts.com/docs/) / [Getting Started](https://oppalerts.com/docs/getting-started/) / Use OppAlerts in Your AI Agent

# Use OppAlerts in Your AI Agent

Ask your AI agent to find link prospects and mentions, or build reports, using OppAlerts data.

With the OppAlerts MCP server, your AI agent can access the same data as the web app. Ask in plain language; the agent chooses the tools, calls them, and reads the results. It can also create and edit your campaigns.

## Set up my agent: one prompt

Copy the text below and paste it into Claude Code, Codex, Claude, Cursor, ChatGPT, or another agent. The agent connects to OppAlerts, asks for the information it needs, and tells you what it did. The same text, with a Copy button, is on the [API & MCP Tokens](https://oppalerts.com/docs/account/api-tokens) page of the web app.

```
Set up OppAlerts in this agent. Do these steps in order, and tell me what
you do at each step.

1. Find out which agent you are. If an OppAlerts connection exists
   already, use it. Do not add a second one.

2. Add the OppAlerts MCP server: https://mcp.oppalerts.com/mcp
   The address without /mcp answers 404. Use the method of this agent to
   add a remote MCP server. If you cannot add it yourself, give me the
   exact command or clicks, and wait for me. The steps for each agent are
   at https://oppalerts.com/docs/getting-started/use-oppalerts-in-your-ai-agent

3. Sign in. The agent finds the OppAlerts login by itself and opens my
   browser. I sign in and allow the read permissions. Ask me to allow the
   edit permissions too, so that you can create and change campaigns.
   If this agent cannot use the browser sign-in, tell me to make a token at
   https://oppalerts.com/app/account/api_tokens and to put it in the secret
   settings of this agent, sent as "Authorization: Bearer <token>". Never
   ask for the token in this chat, and never write it into a repository.

4. Prove the connection: call campaigns_list and account_calls_left.
   Neither is an index search.

5. During the setup, call no news_ or prospects_ tool. Each one is an index
   search. All index searches of the account share one daily count, and
   only one runs at a time.

6. If the account has no campaign, ask me for my website and my market.
   Show me the label, the industry, and a description of 100 to 1,000
   characters before you save them. Then call campaigns_create, then
   campaigns_organization_add for my brand with its site, and for each
   competitor that I name, then campaigns_saved_opportunity_add for the
   opportunity types that I want. The daily opportunities email is off
   until campaigns_set_daily_opportunities_email is called. Ask me for the
   first name, the address, the time zone, the hour, and if I want the
   daily opportunities email. Never guess one of them.
   If a change tool answers that the token has no edit permissions, tell me
   to connect again and allow the edit permissions, or to make a new
   token with the write box ticked.

7. A campaign does not start until it is finalized. After
   campaigns_finalize, the industry and the description cannot change.
   The label, the organizations, and the saved opportunities can.
   Finalize only with my explicit permission. I can give it at the start of
   this task. If you do not finalize, tell me that the campaign has not
   started.

8. Some things are on the OppAlerts website only, as a security precaution:
   tokens, team permissions, the password, billing, and the email notifications
   of the account. Do not try them. Tell me where: the profile menu of
   https://oppalerts.com/app/ links to each page.

9. End with a short report: what is connected, if a campaign exists, and if
   it is finalized. Then give me 3 prompts to try.
```

To connect manually, follow the steps below.

## 1. Connect

Every MCP client uses one URL: `https://mcp.oppalerts.com/mcp`. The bare host, `https://mcp.oppalerts.com`, returns 404. The client discovers the OppAlerts login through `https://mcp.oppalerts.com/.well-known/oauth-protected-resource/mcp`.

### Claude Code

```bash
claude mcp add --transport http oppalerts https://mcp.oppalerts.com/mcp
```

- Then, in Claude Code, type `/mcp`, choose `oppalerts`, and sign in to OppAlerts in the browser.
- The server is added for the current project. Add `--scope user` to use it in all of your projects.

### Claude, on the web and in the desktop app

On a Free, Pro, or Max plan:

1. Open **Customize**, then **Connectors**.
2. Click **Add**, then **Add custom connector**.
3. Enter the name `OppAlerts` and the URL `https://mcp.oppalerts.com/mcp`. Click **Continue**.
4. Keep the options that show **Detected**. Click **Add**.
5. Click **Connect**, and sign in to OppAlerts.

On a Team or Enterprise plan, an Owner adds the connector first: **Organization settings**, **Connectors**, **Add**, **Custom**, then the name and the URL. Each member then opens **Customize**, **Connectors**, finds the connector with the **Custom** label, and clicks **Connect**. Claude's Free plan allows one custom connector.

### Codex

```bash
codex mcp add oppalerts --url https://mcp.oppalerts.com/mcp
```

```bash
codex mcp login oppalerts
```

The second command opens the OppAlerts sign-in page in your browser. To use a token instead, add the server to `~/.codex/config.toml`, and keep the token in the environment variable `OPPALERTS_TOKEN`:

```
[mcp_servers.oppalerts]
url = "https://mcp.oppalerts.com/mcp"
bearer_token_env_var = "OPPALERTS_TOKEN"
```

### Cursor

Add the server to `~/.cursor/mcp.json` for all projects, or to `.cursor/mcp.json` in one project. Cursor opens the OppAlerts sign-in page when the server requests authentication.

```json
{
  "mcpServers": {
    "oppalerts": {
      "url": "https://mcp.oppalerts.com/mcp"
    }
  }
}
```

With a token instead, add `"headers": {"Authorization": "Bearer ${env:OPPALERTS_TOKEN}"}` to the `oppalerts` entry, and keep the token in the environment variable `OPPALERTS_TOKEN`.

### ChatGPT

1. Open `https://chatgpt.com/plugins`.
2. Click the plus button, then **Add custom MCP server**.
3. Enter a name and description.
4. Under **Connection**, enter the server URL `https://mcp.oppalerts.com/mcp`.
5. Set the authentication to OAuth, read the warning, and click **I understand and want to continue**.
6. Click **Create as a plugin**, and sign in to OppAlerts.

Your ChatGPT plan or workspace must allow custom MCP servers.

### Other MCP clients

- Add a remote MCP server, or a custom connector, with the URL `https://mcp.oppalerts.com/mcp`.
- A client that cannot sign in with OAuth can send a token in the header `Authorization: Bearer YOUR_TOKEN`. Keep the token in the client's secret settings. Never paste it into a chat or a file in a repository. See [Create an API Token](https://oppalerts.com/docs/getting-started/create-an-api-token).

## 2. Log in

- The client opens a browser window for the OppAlerts login.
- Log in and allow the read permissions. To let the agent change your campaigns, allow the edit permissions too.
- The page [oppalerts.com/app/account/api_tokens](https://oppalerts.com/app/account/api_tokens) lists each connected app under **Connected apps**. **Disconnect** removes one.
- An app connected before this release can read data but cannot edit campaigns. Connect it again. See [Authentication](https://oppalerts.com/docs/getting-started/authentication#scopes).

## 3. Ask your first question

Start with a question that does not use an index search:

```
List my OppAlerts campaigns, and tell me how many calls I have left today.
```

The agent calls [`campaigns_list`](https://oppalerts.com/docs/mcp/campaigns_list) and [`account_calls_left`](https://oppalerts.com/docs/mcp/account_calls_left).

## Prompts to try

- "Find guest post opportunities for my Hotels campaign on sites with a domain PageRank of 20 or more. Group them by site, and give me the contact page of each site."
- "Which pages named my competitors in the last 30 days but did not name us? Sort them by domain PageRank."
- "Find pages that mention my brand without a link to my site. Give me the page, the sentence, and the contact details of the site."
- "Which sites link to at least two of my competitors and not to me? Use the backlink database, at the domain level."
- "Which sites do the AI models recommend in my market? Mark the ones that are not in my campaign."
- "Read the new pages of my saved opportunities from yesterday, and write me a short summary for each one."

## Prompts that change a campaign

These prompts require edit permissions. The agent uses the tools listed in [Change a campaign](https://oppalerts.com/docs/account/#change).

- "Add example-rival.com as a competitor to my Hotels campaign, with the brand name Example Rival."
- "Save Guest Posts and Podcast Guesting as opportunities of my Hotels campaign."
- "Send the daily opportunities email of my Hotels campaign to marketing@example.com."
- "Set up a campaign for example.com. Ask me before you finalize it."

A campaign does not start until it is finalized. An agent finalizes only with your permission. If it does not finalize the campaign, it tells you. [Campaigns](https://oppalerts.com/docs/getting-started/campaigns#finalize) has the rules.

## What the agent cannot do

Manage tokens, team permissions, your password, billing, and account email notifications on the website only. The agent tells you where to find these settings. [What stays on the website](https://oppalerts.com/docs/account/#website-only) gives the reason.

## Limits to know

- Every `news_` and `prospects_` tool is an index search. Your account's index searches share one daily count across MCP, the web app, and the API.
- Only one index search runs at a time for each account. A second one at the same time fails with `one_at_a_time`. The agent should wait a few seconds and try again.
- [Usage and Daily Limits](https://oppalerts.com/docs/getting-started/usage-and-daily-limits) lists the limits for each plan.

## More

- [Connect an AI Agent](https://oppalerts.com/docs/mcp/): the MCP reference, the call format, and the errors.
- Each tool has its own MCP page, with every parameter and a full sample response.

## Related Pages

- [Connect an AI Agent](https://oppalerts.com/docs/mcp/) Connect Claude Code, Codex, or another AI agent to the OppAlerts MCP server.
- [Authentication](https://oppalerts.com/docs/getting-started/authentication) Login, API tokens, OAuth, and the scopes.
- [Create an API Token](https://oppalerts.com/docs/getting-started/create-an-api-token) Get a token that lets your code or your AI agent call the OppAlerts API and MCP server.
- [Usage and Daily Limits](https://oppalerts.com/docs/getting-started/usage-and-daily-limits) Know how many calls your account has left today, and see who used them.
- [How to Monitor Competitor Mentions](https://oppalerts.com/docs/how-to/monitor-competitor-mentions) Know where your competitors are mentioned, and find the coverage that your business is missing.
