Watchr

Watchr MCP Server

Bring competitive intelligence and brand monitoring into your AI assistant. Ask Claude, Cursor, or any MCP-compatible client what your competitors did this week. Answers come straight from your Watchr workspace.

Watchr is a competitive intelligence and brand monitoring platform. It watches your competitors' websites, ads, social posts, news, and other sources, then qualifies each signal against a prompt you define, so what you see is *relevant* movement, not noise.

This repository documents the official Model Context Protocol (MCP) server for Watchr. It exposes account-scoped data and controlled account workflows. API keys provide read access; authorized OAuth administrators can also configure watchlists, manage members, record feedback and manage account tags.

The server is hosted by Watchr. No local install, no Docker. Just point your client at https://mcp.watchr.ai/mcp and authenticate. There are two paths, depending on your client:

• One-click OAuth for Claude (Desktop / Code), ChatGPT, Cursor and any other client supporting Dynamic Client Registration. Browser opens, you approve, done.
• Personal API key (generated in your Watchr workspace) for agentic frameworks and custom integrations where you embed the MCP into your own automation stack.

---

Table of contents

• What you can do with it
• Showcase
• Available tools
• Insight response contract
• Onboarding skill for Claude Code and Codex
• Getting started with Watchr
• Authentication
• Option A. One-click OAuth
• Option B. Personal API key
• Configuration
• OAuth clients
• API key clients
• Improving your results
• Support

---

What you can do with it

Once connected, you can ask your AI assistant things like:

• *"What did our competitors launch this week?"*
• *"Draft a Slack message summarizing the top 5 competitive insights from this month."*
• *"Compare positioning changes across our tracked brands over the last 30 days."*
• *"Build me a one-page competitive briefing on HubSpot from the last month, make it visual."*
• *"Automatically update my Notion battle cards and competitor recap pages with this week's Watchr insights."*

The MCP server provides the data; your assistant handles the reasoning, drafting, and integration with the rest of your workflow.

Showcase

A short conversation with Claude pulling the latest HubSpot signals through Watchr:

Same data, one follow-up prompt later. Claude generates a designed competitive briefing artifact directly from the validated Watchr insights:

This is the core loop. Watchr collects and qualifies. Your AI client reasons and outputs. The MCP server is the glue.

Available tools

The default endpoint exposes 37 tools, including reads and writes. The dedicated ChatGPT profile exposes 62 tools, with individually named configuration preview/apply actions. Runtime tools/list is the source of truth for arguments, schemas and permissions.

Collections support their documented pagination and filters. Configuration uses a persistent preview followed by explicit approval before application. Reads require mcp:read; configuration and tag writes additionally require mcp:configure; member administration requires mcp:members:manage. Current roles and permissions are checked server-side. API keys remain read-only.

Previewing does not start collection, send emails or apply a change. Some apply actions launch external discovery or collection. Tag definitions do not reclassify history: classification jobs are explicit, bounded and budgeted, and preserve manual corrections by default. Recorded relevance feedback does not change qualification or perform replay.

New MCP-created watchlists have report preparation and email delivery disabled by default. Those two effects share one setting; disabling it does not stop collection. Existing report preferences are preserved.

Insight response contract

search_insights returns a compact discovery payload. Every item includes an id, a title, a factual summary, source and brand metadata, and an effective_date. The accompanying date_type says whether that effective date is the source publication date (published) or Watchr's detection date (detected). Website changes therefore remain safely dateable even when they have no publication date.

The search response intentionally omits the original description, qualification_analysis, raw dates, and related_items. This keeps result pages small enough for an AI client to rank and shortlist without spending its context window on source text it may never use.

When an item's title or summary is not clear enough, call get_insight with the returned id as insight_id before answering. get_insight provides the source description, qualification reasoning, published and detected dates, and any related validated insights. Consumers should not infer missing detail from the compact summary alone.

search_signals and get_signal expose watchlist-scoped topics, source relations and recorded report appearances. competitive_signal_id is a legacy shared grouping hint, not the authoritative topic identity. Historical report appearances may be unavailable when no structure was recorded. A stored snapshot timestamp is not proof of the actual screenshot capture time.

Onboarding skill for Claude Code and Codex

The Watchr onboarding skill helps an authorized assistant read your current setup, prepare a first watchlist or improve an existing one, show the exact preview, and verify the result after your approval. The skill and the MCP connection are separate: installing the skill does not grant access or change your account.

To install it for one project, copy the entire skills/watchr-onboarding/ directory from this repository to .claude/skills/watchr-onboarding/ for Claude Code or .agents/skills/watchr-onboarding/ for Codex. For a personal installation, use ~/.claude/skills/watchr-onboarding/ or ~/.agents/skills/watchr-onboarding/ respectively. Keep both SKILL.md and agents/openai.yaml together.

Connect Claude Code with claude mcp add --transport http watchr https://mcp.watchr.ai/mcp, then authorize through /mcp. Connect Codex with codex mcp add watchr --url https://mcp.watchr.ai/mcp/chatgpt, then run codex mcp login watchr. Complete Watchr sign-in only in the browser. Once connected, ask your assistant to use the Watchr onboarding skill.

If you start in Claude Code or Codex without a Watchr account, begin the MCP OAuth connection in that client. The browser opens Watchr's dedicated agent signup page from the validated authorization request, then returns to consent after account creation. The trial begins when the account is created; no watchlist or report email is enabled by signup alone. A direct visit to the page has no OAuth state. Real Claude Code and Codex onboarding with a new empty account still needs end-to-end acceptance testing.

Getting started with Watchr

You need a configured Watchr workspace before the MCP server has anything interesting to return. The full path:

1. Create an account at watchr.ai/signup. A free tier is available.
2. Finalize your settings at watchr.ai/app/settings:

• Add the brands and competitors you want to track
• Specify the market you are monitoring (used to qualify relevance)
• Subscribe to the newsletters and press feeds you want pulled in
• Add the pages you want Watchr to monitor for changes (pricing, changelog, careers, etc.)
• Add social media profiles to scrape (LinkedIn, Facebook, Instagram)

1. Wait for the first collected insights. Report pr