Documentation / 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 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

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

codex mcp add oppalerts --url https://mcp.oppalerts.com/mcp
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.

{
  "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.

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

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

  • "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 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 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 lists the limits for each plan.

More

  • Connect an AI Agent: the MCP reference, the call format, and the errors.
  • Each tool has its own MCP page, with every parameter and a full sample response.