# CardScope > CardScope checks how a link will look when it is shared, before you post it. CardScope is a link-preview and Open Graph checker for developers and AI agents that post links and need to check the card first. Send a URL. It reads the HTML the server returns and reports the title, description, image, and layout that X, LinkedIn, Slack, Discord, iMessage, Bluesky, Threads, Mastodon, WhatsApp, Telegram, and Microsoft Teams will use, plus what to fix. It does not run JavaScript, and it does not take a screenshot of the rendered page. Page HTML is parsed in memory and discarded. A short index of the same facts is at https://cardscope.dev/llms.txt. The HTML pages are linked below. This file also includes the API reference. ## Pages - [Home](https://cardscope.dev/): Paste a URL and check the card. - [Pricing](https://cardscope.dev/pricing): Web checker prices. Pro is $19 once, not a subscription. - [API](https://cardscope.dev/api): API plans, and the form that emails a free key. - [API reference](https://cardscope.dev/docs/api): GET and POST /v1/preview. - [MCP server](https://cardscope.dev/docs/mcp): Connect Cursor, Claude Code, or VS Code. - [Guides](https://cardscope.dev/guides): Public guides for Open Graph tags and link previews. - [Check a URL](https://cardscope.dev/check): Free web checker. - [Site audit](https://cardscope.dev/site-audit): Reads a sitemap. Free checks the first 3 pages. - [OG tag generator](https://cardscope.dev/og-tag-generator): Free tool to write Open Graph tags. - [OG image resizer](https://cardscope.dev/og-image-resizer): Free tool to resize an og:image. - [Link preview mockup](https://cardscope.dev/link-preview-mockup): Free mockup of a link card. - [GitHub Action](https://cardscope.dev/docs/github-action): Check previews from CI. - [Dashboard](https://cardscope.dev/api/dashboard): Plan, usage, and upgrade for an API key. ## MCP The remote MCP server is Streamable HTTP, with no session, at https://cardscope.dev/mcp. Tools: - check_link_preview: url is required, platforms is optional. Returns the same JSON as /v1/preview, then a one-line summary. The summary counts every warning and error in issues, and every info row as a note. platforms filters both the cards and that list. - list_platforms: the 11 apps and the doc URLs each rule cites. Without a key, the server allows 20 calls a day from one IP. A free key is 300 previews a month. An invalid key is rejected. It does not fall through to the anonymous allowance. Do not put the key in a chat you share. Cursor, in ~/.cursor/mcp.json or the project .cursor/mcp.json. Leave the header off until the key arrives: ```json { "mcpServers": { "cardscope": { "url": "https://cardscope.dev/mcp" } } } ``` With a key: ```json { "mcpServers": { "cardscope": { "url": "https://cardscope.dev/mcp", "headers": { "Authorization": "Bearer cs_live_…" } } } } ``` Claude Code: ``` claude mcp add cardscope --transport http https://cardscope.dev/mcp \ --header "Authorization: Bearer cs_live_…" ``` Omit --header to use the anonymous allowance. VS Code, in .vscode/mcp.json: ```json { "servers": { "cardscope": { "type": "http", "url": "https://cardscope.dev/mcp", "headers": { "Authorization": "Bearer cs_live_…" } } } } ``` The registry name is dev.cardscope/link-preview. ## Pricing The web checker and the API are separate. Web checker, at https://cardscope.dev/pricing. A free check shows previews in 11 apps and the fix checklist. Pro removes the daily limit. One payment, not a subscription. - Without Pro: Free. Previews in 11 apps and the fix checklist. The meta tags on the page. A site audit reads the sitemap and checks the first 3 pages. No account. - Pro: $19. One payment. Not a subscription. Unlimited checks, shareable report links that last 7 days, and PNG export. A site audit of up to 50 pages, with a CSV of the results. Unlocks this browser right away. Use your license key to unlock other devices. API, at https://cardscope.dev/api. Monthly subscriptions, billed by Stripe. Upgrade from the dashboard with your key. A preview we attempt counts, including when the site does not respond. A URL we reject does not. Five requests a second. The count resets at the start of the next UTC month. - Free: $0. 300 previews a month. One key by email. All 11 apps. 5 requests a second. - Starter: $9. 10,000 previews a month. Same response. Stripe subscription. Cancel in the billing portal. - Pro: $29. 100,000 previews a month. For a product that checks links on a schedule. Cancel in the billing portal. The $19 one-time license is the web checker: unlimited checks in the browser, the 50-page site audit, share links, and PNG export. It is not an API key. ## Free API key Get a free key at https://cardscope.dev/api#get-key. Enter an email. We email a link. The page shows the key once, with the curl and MCP snippets filled in. We store a hash, not the key. Do not put the key in a browser page or a public repo. From your own code, POST https://cardscope.dev/api/keys with {"email":"you@example.com"}. GET https://cardscope.dev/api/keys/claim?token=… shows the key once. The key is a secret: server-side code, a GitHub Actions secret, or an MCP config on your machine. Do not put it in a page you publish. ## API reference Free is 300 previews a month. Starter is $9 for 10,000. Pro is $29 for 100,000. ``` curl -sS "https://cardscope.dev/v1/preview?url=https://example.com" \ -H "Authorization: Bearer cs_live_…" ``` ### Request GET /v1/preview?url=&platforms=x,slack&source=api POST /v1/preview with a JSON body accepts the same fields. platforms is optional (all 11 apps when omitted). source is api, mcp, or action. It only changes which counter we increment. The default is api. Header: Authorization: Bearer cs_live_…. The token is at least 32 characters after cs_live_. GET responses send Access-Control-Allow-Origin: *. That does not make a browser call safe. The key is still visible to anyone who can read the request. ### Response The TypeScript shape is LinkPreview in src/lib/preview.ts. - url, finalUrl, status (HTTP status of the page), fetchedAt - tags.og, tags.twitter, tags.meta (title, description, canonical) - image: url, reachable, width, height, bytes, contentType - platforms[]: id, name, title, description, image, layout (large, small, or none), truncated (title and description booleans), usedFallbacks, warnings, sources (the doc URLs cited in the checker; empty when we do not cite one) - issues[]: checklist items with id, severity (error, warn, info, or ok), title, fix, platforms. When platforms is set, this list keeps items that name one of those apps, and each item's platforms is cut down to the ones you asked for. The MCP summary counts the warnings and errors in this list as issues, and the info rows as notes. - usage: plan (free, starter, pro), used, limit, resetsAt ### Errors - 400: the URL is missing, not http(s), or a private or reserved address - 401: missing or invalid key - 402: quota_exceeded, with upgradeUrl and usage - 422: the fetch failed. message is the reason. The call still counts. - 429: more than 5 requests in the same second for that key ### Quotas Free 300, Starter 10,000, Pro 100,000 previews each UTC month. The counter key is api:{keyId}:{YYYY-MM}, so the next month starts at zero. A rejected URL (400) and a rate-limited call (429) do not count. A fetch we attempt does, including a 422. Every response with a usage count sends X-CardScope-Limit, X-CardScope-Used, and X-CardScope-Remaining. When the key has used at least 80% of the month, the response also sends X-CardScope-Upgrade with the URL of the API page (Starter $9, Pro $29). A 402 still includes upgradeUrl in the JSON. The dashboard shows the same 80% line above the upgrade buttons. No email is sent for this. ### Keys POST /api/keys with {"email":"you@example.com"} emails a one-time link. GET /api/keys/claim?token=… shows the key once. GET /api/keys/me returns the plan and this month's usage. POST /api/keys/rotate returns a new key and revokes the one you sent. POST /api/keys/upgrade with {"plan":"starter"} or "pro" returns a Stripe Checkout URL. POST /api/keys/portal returns a billing portal URL after the first payment. ## Optional - [Privacy](https://cardscope.dev/privacy): What is stored, and what is discarded. - [Terms](https://cardscope.dev/terms): Terms of use.