Agents, API & MCP

Server URL

All clients use the same Streamable HTTP endpoint:

https://competescan.com/api/mcp

Authenticate with a workspace API key as Authorization: Bearer cs_…. The key only works for the workspace that created it, and every call respects that workspace's plan.

1. Create a key

1. Sign in and open Settings → API & agents. Only a workspace owner can create or revoke keys.
2. Name the key after the client that will use it — Claude Code, Cursor laptop — then create it.
3. Copy the secret immediately. It starts with cs_ and is shown once. Treat it like a password: anyone with it can read this workspace and write to the playbook.

The Last used column updates each time the key is used, so unused ones are easy to spot. Revoke a key any time; clients using it lose access immediately. A workspace whose subscription ended keeps its keys, but they return 402 until it resubscribes.

2. Connect a client

Claude Code

In a terminal:

claude mcp add competescan --transport http https://competescan.com/api/mcp \
  --header "Authorization: Bearer cs_YOUR_KEY"

The first tool call uses the key in the header. There is no OAuth step.

Cursor

1. Open Cursor Settings → Tools & MCP.
2. Add a custom MCP server with Streamable HTTP, or put this in ~/.cursor/mcp.json. Keep the key out of the repo — a project .cursor/mcp.json gets committed.

{
  "mcpServers": {
    "competescan": {
      "url": "https://competescan.com/api/mcp",
      "headers": {
        "Authorization": "Bearer cs_YOUR_KEY"
      }
    }
  }
}

VS Code (GitHub Copilot)

Add a .vscode/mcp.json file to your workspace, or open the MCP: Open User Configuration command:

{
  "servers": {
    "competescan": {
      "type": "http",
      "url": "https://competescan.com/api/mcp",
      "headers": {
        "Authorization": "Bearer cs_YOUR_KEY"
      }
    }
  }
}

REST

The same operations are plain HTTPS. Send the key as a bearer token. On POSTs, an Idempotency-Key header makes retries safe: repeating a key returns the first response instead of creating a duplicate.

curl https://competescan.com/api/v1/cards?type=onsite \
  -H "Authorization: Bearer cs_YOUR_KEY"

curl -X POST https://competescan.com/api/v1/cards/CARD_ID/items \
  -H "Authorization: Bearer cs_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: onsite-faq-schema-pricing" \
  -d '{"text":"Add FAQPage schema to /pricing","details":{"page":"/pricing","test":"Rich Results Test shows FAQPage"}}'

Other platforms

Any MCP client that speaks Streamable HTTP can use https://competescan.com/api/mcp with the same Authorization: Bearer header. There is no OAuth flow yet.

3. Verify the connection

After setup, ask your agent:

Read my CompeteScan context. What are the three buyer prompts I lose most often, who wins them, and which pages do the engines cite?

You should get an answer about this workspace's brand, drawn from the latest scan. If that works, you're set. From here, paste one of the workflows below, or browse the reference.

4. How the playbook is shaped

A card is one piece of work on the board: a content cluster, a citation push, an on-site fix. It holds elements of its own type, one or many. Each element has a status (todo, in_progress, done, cancelled), a stage, and typed details. Drafts and pull requests stay where they live; agents link them in a comment.

The API refuses the stages marked person-only. An agent can move content to drafted, but a teammate approves and publishes it. Unknown detail keys are rejected with a message naming the allowed ones.

5. Reference

Errors come back as { "error": "code", "message": "…" } with a 4xx status. Keys are limited to 120 calls a minute.

6. Workflows

Paste one of these into your agent as a starting prompt. Each one writes its results back into CompeteScan.

On-site: fix what AI crawlers trip on

1. Call list_cards with type onsite and read get_context for pages and crawler policy.
2. For each issue, create_element on the card with a page and a test that proves the fix.
3. Fix it in the repo, move the element to shipped, and add_comment with the pull request link.

Content: from gaps to drafts

1. Read get_context: prompts you lose, who wins them, and what the engines cite.
2. create_card per topic cluster, with idea elements carrying keywords and reasoning.
3. After your team picks the ideas to pursue, write outlines and drafts, move them to outlined and drafted, and comment with links to the drafts.

Citations: other websites worth getting on

1. Read sources and competitors from get_context.
2. On a citations card, create one element per target with url, cost, price, and how, at stage suggested.
3. Your team approves the list; the agent can then run outreach and move targets to outreach, pending, and live.

Troubleshooting

Unauthorized or invalid_api_key

• Confirm the key starts with cs_ and was copied in full.
• Check it hasn't been revoked in Settings → API & agents.
• The Authorization: Bearer … header must be sent on every request.

plan_required (402)

• The workspace is no longer on a paid plan. Resubscribe and the same key works again.

Connection timeout

• The URL must be exactly https://competescan.com/api/mcp.

Questions or a workflow you want documented? Get in touch or email support@competescan.com.