Averra Extract MCP

Convert any webpage URL into clean, LLM-ready Markdown using Averra Extract.

This tool fetches the page (executing JavaScript via a headless browser), strips navigation/ads/UI clutter via Mozilla Readability, converts the main content to Markdown, and returns it along with metadata (title, word count, links, language). Results are cached for 7 days and shared across users.

Use this when you need the actual content of a webpage for an LLM — e.g. reading a blog post, docs page, article, or product page to answer a question or synthesize information.

Args:

• url (string, required): The webpage URL. Accepts https://example.com or bare example.com (https:// is auto-added). Max 2048 chars.

• response_format ('markdown' | 'json', optional): Output format. Default 'markdown'.

Returns: For JSON format, structured data: { "markdown": string, // Clean markdown content of the page "metadata": { "title": string, // Page title (from first H1 or URL fallback) "word_count": number, // Word count of extracted text "links": string[], // Unique URLs found in the content "language": string, // "en" or "unknown" "timestamp": string // ISO 8601 extraction time }, "warning": string (optional) // Present if content is thin (<200 words) }

For Markdown format: a formatted document with title, metadata summary, and the extracted markdown.

Counts against your monthly Extract quota (including cached requests). Use averra_check_usage to see remaining quota.

Examples:

• Use when: "Summarize this blog post: https://example.com/post" → extract then summarize

• Use when: "What does this docs page say about auth?" → extract then answer

• Don't use when: You just need a link preview or metadata (this returns full content)

• Don't use when: You need JSON extraction with a schema (not supported yet)

Error Handling:

• 400: URL rejected by safety checks (malformed, private IP, unreachable host) — check the URL resolves publicly.

• 401: Invalid API key — check AVERRA_EXTRACT_API_KEY env var

• 404: Page not found at URL

• 429: Monthly limit exceeded — upgrade plan or wait

• 502/503/504: Scraping service temporarily unavailable — retry

Check the current month's Extract API usage and remaining quota for the authenticated account.

Usage is counted per user across all API keys (not per key). Cached requests also count against the quota. The counter resets at the start of each calendar month (UTC).

Args:

• response_format ('markdown' | 'json', optional): Output format. Default 'markdown'.

Returns: For JSON format: { "plan": "free" | "starter" | "pro" | "scale", "monthly_limit": number, // Max requests allowed this month "used": number, // Requests made so far this month "remaining": number // max(0, monthly_limit - used) }

For Markdown format: a summary showing plan, limit, used, and remaining.

Examples:

• Use when: "How many extracts do I have left this month?"

• Use when: Before a batch of extracts, to confirm sufficient quota.

• Use when: User asks "Am I on the free plan?" — the plan field answers this.

Error Handling:

• 401: Invalid API key — check AVERRA_EXTRACT_API_KEY

Create a new Extract API key for the authenticated account.

IMPORTANT: The plaintext key is returned ONLY ONCE in this response. It cannot be retrieved later — only the prefix is stored for display. If lost, the key must be revoked and a new one created.

The new key automatically inherits the plan and limits from your account's current subscription. You cannot choose a plan — it is determined by your billing state.

Args:

• response_format ('markdown' | 'json', optional): Output format. Default 'markdown'.

Returns: For JSON format: { "key": string, // FULL plaintext key (shown once) — format: sk_live_<48 hex> "id": string, // Key ID for management operations "prefix": string, // First 12 chars (for display/reference) "plan": "free" | "starter" | "pro" | "scale", "monthly_limit": number, "created_at": string, // ISO 8601 "warning": string // Reminder to save the key }

Examples:

• Use when: User wants to create a new API key for a different integration.

• Use when: Rotating keys (create new, then revoke old).

• Don't use without user confirmation — this creates a credential the user must save.

Error Handling:

• 401: Invalid API key — check AVERRA_EXTRACT_API_KEY

• 500: Database error — retry

List all API keys for the authenticated account.

Returns metadata only — the actual plaintext keys are never returned (only prefixes). Includes both active and revoked keys, ordered by creation date (newest first).

Args:

• response_format ('markdown' | 'json', optional): Output format. Default 'markdown'.

Returns: For JSON format: { "keys": [ { "id": string, // Key ID (use for revoke operations) "key_prefix": string, // First 12 chars of key "plan": "free" | "starter" | "pro" | "scale", // Decorated from the account profile — identical across every key on the account. "monthly_limit": number, // Decorated from the account profile — identical across every key on the account. "is_active": boolean, // false if revoked "created_at": string, // ISO 8601 "revoked_at": string | null // ISO 8601 if revoked, null otherwise } ] }

Examples:

• Use when: User asks "How many API keys do I have?"

• Use when: Need to find a key's ID before revoking it.

• Use when: Auditing which keys exist and their plans.

Error Handling:

• 401: Invalid API key — check AVERRA_EXTRACT_API_KEY

Revoke an Extract API key by its ID. The key is immediately deactivated and cannot be reactivated — create a new key if needed.

SAFETY: You cannot revoke the key that is currently authenticating the MCP server itself (the one set in AVERRA_EXTRACT_API_KEY). Attempting to do so returns a 400 error.

Args:

• id (string, required): The key ID to revoke. Get this from averra_list_api_keys.

• response_format ('markdown' | 'json', optional): Output format. Default 'markdown'.

Returns: For JSON format: { "message": "API key revoked", "id": string, // The revoked key's ID "prefix": string, // Key prefix for confirmation "revoked_at": string // ISO 8601 revocation time }

This operation is destructive (cannot be undone) but idempotent (revoking an already-revoked key is safe).

Examples:

• Use when: User explicitly asks to revoke a specific key.

• Use when: Rotating keys — after confirming the new key works.

• Don't use without user confirmation — this invalidates a credential.

Error Handling:

• 400: Attempting to revoke the currently-authenticating key — use a different auth key first

• 401: Invalid API key — check AVERRA_EXTRACT_API_KEY

• 404: Key not found or already revoked