Model Context Protocol

Connect an AI assistant to Competitor Tracker & Co. over the Model Context Protocol: Streamable HTTP endpoint, OAuth or API-key auth, plus the tools it exposes.

The Model Context Protocol (MCP) lets an AI client work your account as a set of tools. It can list your competitors, read the changes we caught and manage your labels. Our lead detective C. T. Lucky minds this door too.

The server is a thin façade over the API these docs already describe. It speaks the protocol, then forwards each call with your credential attached, unchanged. The API stays the one place that decides who you are and what you may touch. Nothing gets checked twice, and your data lives in one place. The server just passes notes.

The endpoint

POST https://mcp.competitortracker.io/mcp

The protocol runs over Streamable HTTP on the /mcp path. A browser that lands on the root of mcp.competitortracker.io gets bounced here, to these docs. Point your MCP client at the /mcp URL.

Two ways to authenticate

Every call needs a credential, and the server takes either kind the API takes:

OAuth 2.0 bearer token for interactive clients that sign a person in. Send it on the Authorization: Bearer … header.
API key for scripts and headless agents. Send it on the X-API-Key header.

If both headers arrive the API key wins. See Authentication for the OAuth flow and API keys for minting a key.

Connect your client

Point your client at https://mcp.competitortracker.io/mcp and it runs the OAuth handshake on first use, so you sign in and pick an organization once. Headless clients skip that and send an API key on the X-API-Key header instead.

We keep a setup recipe for each client — Claude, Codex, Cursor, Zed, Cline and a dozen more — over on Connect a client. Every recipe has its own linkable section.

OAuth discovery

MCP clients work out where to sign in by reading a 401. Call /mcp with no credential and the server answers:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.competitortracker.io/.well-known/oauth-protected-resource"

Follow that URL for the RFC 9728 protected-resource metadata. It names the authorization server (auth.competitortracker.io) and the resource the token is for. From there a client registers itself, runs the PKCE flow against auth.competitortracker.io and comes back with a token. The MCP server mints nothing of its own.

GET https://mcp.competitortracker.io/.well-known/oauth-protected-resource

Scopes and roles

Each tool maps to one API endpoint, so it inherits that endpoint's requirements. The tool reference names the scope every tool needs: competitors:read to list competitors, labels:write to create a label. Your token or key has to carry that scope, and your role in the organization has to allow the action. A call that falls short comes back as a plain tool error with the reason spelled out.

When the API asks you to slow down, that arrives the same way: a tool error telling you to back off. The MCP server runs no limiter of its own.

Destructive tools

Some tools remove things for good: unsubscribing from a competitor, deleting a label, revoking an invite. Each one takes a required confirm field that has to be true:

{
  "name": "unsubscribe_competitor",
  "arguments": { "id": "01HF…", "confirm": true }
}

Leave confirm out and we refuse the call before it reaches the API, so nothing goes missing by accident. The reference marks every destructive tool.

The tool catalog

The MCP tools page lists every tool, its parameters and its behavior hints. It is generated from the live definitions, so it tracks what the server actually serves.