Documentation / MCP / Connect an AI Agent
Connect an AI Agent
POSThttps://mcp.oppalerts.com/mcp
Connect Claude Code, Codex, or another AI agent to the OppAlerts MCP server.
What the MCP server is
The OppAlerts MCP server lets an AI agent, such as Claude Code or
Codex, call OppAlerts tools. Every tool uses the same URL:
https://mcp.oppalerts.com/mcp. The request includes the tool name.
Connect Claude Code
claude mcp add --transport http oppalerts https://mcp.oppalerts.com/mcp
The first call opens a browser window for the OppAlerts login. The
server uses OAuth 2.0 with PKCE from https://auth.oppalerts.com.
claude mcp add command to the first tool call.Source: a new screen recording.
File:
img/docs/mcp/connect.mp4
How a call looks
An MCP call is a JSON-RPC request to POST https://mcp.oppalerts.com/mcp
with the token in the Authorization: Bearer header.
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "account_calls_left",
"arguments": {}
}
}
Rules for every call
- Authentication. Every call needs a token in the
Authorization: Bearerheader: a personal token or an OAuth access token. The MCP server needs the scopemcp:use. A tool that changes data also needsapi:write. A missing or invalid token returns HTTP 401unauthorized. See Authentication. - Daily limits. The 14
news_andprospects_tools are index searches. All index searches for an account share one daily count. Every other tool has a daily count of its own. Team members use the account’s counts. The counts reset every day at 04:00 New York time.account_calls_leftshows the calls left today. A call over a count is refused withdaily_limit(HTTP 429 in the API). - What counts. Each tool call through the API or MCP uses one call from its daily count. A refused call with an HTTP status from 400 to 499 uses no daily call. Two responses are not refusals and use one call: a search stopped by the index (HTTP 422), and a server error (HTTP 500 to 599). The MCP messages
initialize,tools/list, andpingare not tool calls and use no daily call. Calls from web app pages use the same counts, except when one of these 12 tools reads data from your own account:campaigns_list,campaigns_settings,campaigns_organizations,campaigns_saved_opportunities,campaigns_dashboard,account_usage,account_team_members,account_calls_left,llm_answers_content_phrases,llm_answers_search_keywords,llm_answers_top_sites, andtaxonomy_taxonomies. - One search at a time. Only one index search runs at a time for each account. A call to a
news_orprospects_tool made while another index search runs is refused withone_at_a_time(HTTP 429 in the API) and uses no daily call. Wait a few seconds and send it again. - One change at a time. Only one change runs at a time for each account. A call to one of the 16 tools that change data, made while another change is running for the account, is refused with
one_at_a_time(HTTP 429 in the API) and uses no daily call. Send it again after a few seconds. The 16 tools:campaigns_create,campaigns_update,campaigns_finalize,campaigns_archive,campaigns_activate,campaigns_rerun_research,campaigns_rebuild_counts,campaigns_set_taxonomy_presets,campaigns_set_daily_opportunities_email,campaigns_organization_add,campaigns_organization_update,campaigns_organization_delete,campaigns_saved_opportunity_add,campaigns_saved_opportunity_update,campaigns_saved_opportunity_archive, andcampaigns_saved_opportunity_activate. - Request log. Each tool call with a valid token is written to the account’s request log: the time, the source, the token, the tool, the HTTP status, and whether it used a daily call. Refused calls are also logged. The MCP messages
initialize,tools/list, andpingare in the log withcountedfalse. A call ofaccount_calls_leftthrough the API or MCP is never logged.account_usageand the Usage page of the web app show the log for the last 14 days.
The API page lists the daily counts of each plan.
Errors
A refused tool call returns a normal JSON-RPC response with
"isError": true. Its text starts with the error code, the same
code that the API returns, then a colon and one sentence:
{
"content": [
{"type": "text", "text": "no_campaign: That campaign is not in this account."}
],
"isError": true
}
The API page lists the error codes that many tools share. Each tool’s page lists its error codes.
One type of refusal is not a tool result. When the token does not have a scope
that the call needs, the server returns HTTP status 403, as the MCP
standard requires. The response has a WWW-Authenticate header with
error="insufficient_scope" and the scopes that the call needs.
An MCP app that reads this header asks you for those permissions. An example: a
tool that changes a campaign, called by an app that can only read. The response
body has the error code forbidden and one sentence.
All tools
The server has 50 tools, in 10 groups. Each tool has an MCP page and an API page.
Account (3)
account_calls_left: Calls Left Todayaccount_team_members: Team Membersaccount_usage: Account Usage
Backlinks (2)
backlinks: Backlinks of One or More Sitesbacklinks_link_gap: Backlink Gap
Campaigns (21)
campaigns_activate: Activate a Campaigncampaigns_archive: Archive a Campaigncampaigns_create: Create a Campaigncampaigns_dashboard: Campaign Dashboardcampaigns_finalize: Finalize a Campaigncampaigns_list: Campaign Listcampaigns_organization_add: Add an Organizationcampaigns_organization_delete: Delete an Organizationcampaigns_organization_update: Update an Organizationcampaigns_organizations: Campaign Organizationscampaigns_rebuild_counts: Rebuild the Daily Countscampaigns_rerun_research: Run Stopped Research Againcampaigns_saved_opportunities: Saved Opportunitiescampaigns_saved_opportunity_activate: Activate a Saved Opportunitycampaigns_saved_opportunity_add: Add a Saved Opportunitycampaigns_saved_opportunity_archive: Archive a Saved Opportunitycampaigns_saved_opportunity_update: Update a Saved Opportunitycampaigns_set_daily_opportunities_email: Set the Daily Opportunities Emailcampaigns_set_taxonomy_presets: Set Taxonomy Presetscampaigns_settings: Campaign Settingscampaigns_update: Update a Campaign
Link Graph (1)
linkgraph_history: PageRank History
LLM Answers (3)
llm_answers_content_phrases: AI Content Phrasesllm_answers_search_keywords: AI Search Keywordsllm_answers_top_sites: Top Sites Named by AI
News Index (7)
news_brand_link_gap: News Link Gapnews_brand_links: News Pages Linking to Brandsnews_brand_mentions: News Brand Mentionsnews_opportunities: News Opportunitiesnews_search: News Searchnews_similar_to_id: Similar News Pagesnews_unlinked_brand_mentions: News Unlinked Brand Mentions
Prospect Index (7)
prospects_brand_link_gap: Prospect Link Gapprospects_brand_links: Prospect Pages Linking to Brandsprospects_brand_mentions: Prospect Brand Mentionsprospects_opportunities: Prospect Opportunitiesprospects_search: Prospect Searchprospects_similar_to_id: Similar Prospect Pagesprospects_unlinked_brand_mentions: Prospect Unlinked Brand Mentions
Site Info (1)
siteinfo_site: Site Contact Details
Taxonomies (3)
taxonomy_categories: Taxonomy Categoriestaxonomy_semantic_content_analyzer: Semantic Content Analyzertaxonomy_taxonomies: Available Taxonomies
Types (2)
types_content_types: Content Typestypes_opportunity_types: Opportunity Types