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, chooseoppalerts, and sign in to OppAlerts in the browser. - The server is added for the current project. Add
--scope userto use it in all of your projects.
Claude, on the web and in the desktop app
On a Free, Pro, or Max plan:
- Open Customize, then Connectors.
- Click Add, then Add custom connector.
- Enter the name
OppAlertsand the URLhttps://mcp.oppalerts.com/mcp. Click Continue. - Keep the options that show Detected. Click Add.
- 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
- Open
https://chatgpt.com/plugins. - Click the plus button, then Add custom MCP server.
- Enter a name and description.
- Under Connection, enter the server URL
https://mcp.oppalerts.com/mcp. - Set the authentication to OAuth, read the warning, and click I understand and want to continue.
- 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_andprospects_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.