# Prowl — MCP-Native Market Intelligence Platform

> https://prowl.chat

## Overview

Prowl is **the MCP that turns any AI agent into a research analyst**. It is not a research tool — it is the intelligence layer your agents connect to. External agents connect via **Model Context Protocol (MCP)** at `https://prowl.chat/mcp` and instantly gain **448 intelligence tools** (DataForSEO, SearchAPI, SerpAPI, web scraping, SEO, ads, AI) so they answer with **real numbers, not guesses** — all on **pay-as-you-go USD wallet billing**.

Humans use the web UI as a secondary dashboard: wallet balance, API keys, top-up, and chat-based reports.

## MCP Quick Start

1. Sign up at https://prowl.chat
2. Open **MCP Home** → generate an API key (`prowl_…`)
3. Configure your MCP client:

```json
{
  "mcpServers": {
    "prowl": {
      "url": "https://prowl.chat/mcp",
      "headers": { "Authorization": "Bearer prowl_YOUR_KEY" }
    }
  }
}
```

4. Call `prowl_list_tools` → `prowl_tool_info` → `prowl_call_tool` for direct tool access, or `prowl_analyze` for a full strategy report.

**Fast path:** hand a coding agent the install skill and it wires up the client config + token file itself. Paste: *"Set up the Prowl MCP using the install skill at https://prowl.chat/mcp/install.md — my token is prowl_YOUR_KEY."* The landing page and MCP Home both have a "Copy agent install prompt" button. Installable plugin: https://github.com/PROWL-AI/prowl-skill

Full agent documentation: https://prowl.chat/mcp/skill.md
Agent install skill: https://prowl.chat/mcp/install.md

## Billing Model (USD wallet)

Two balance pools per account:

| Pool | Source | Expiry | Charged |
|------|--------|--------|---------|
| **Subscription** | Stripe plan (Exploit / Blackops / Syndicate) | Burns at period end | 1st |
| **Extra** | One-time top-up packs ($10 / $50 / $200) | Never expires | 2nd |

Every `prowl_call_tool` invocation debits wallet balance: **provider cost × markup** (uniform `MCP_BILLING_MARKUP`, default 1.5×). Response JSON includes a `billing` object (`estimated_cost_usd`, `actual_cost_usd`, `debited`). Check balance via `GET /api/v1/wallet` (JWT) or MCP Home.

Public price catalog: `GET /api/v1/tools/pricing` (includes `estimated_billed_usd`)

Agent REST v1: `GET /api/v1/wallet`, `/api/v1/wallet/invocations`, `/api/v1/usage/tools`, `/api/v1/usage/summary`, `/api/v1/tools/pricing`, `GET/POST/DELETE /api/v1/keys`

## Subscription Tiers (monthly credit bundles)

| Tier | Price | Credit / period | Best for |
|------|-------|-----------------|----------|
| Recon | Free | $5 starter credit (extra pool) | Try MCP |
| Exploit | $60/mo | $60 USD credits | Founders |
| Blackops | $120/mo | $120 USD credits | PMMs / operators |
| Syndicate | $240/mo | $240 USD credits | Agencies / teams |

Yearly plans available (≈10× monthly credit bundle). Top-up anytime via Stripe credit packs.

## MCP Tools (22 registered, 448 underlying)

| Tool | Purpose |
|------|---------|
| `prowl_analyze` | Full multi-agent competitive intelligence report |
| `prowl_list_tools` | Browse tool bank by category |
| `prowl_tool_info` | JSON schema for a tool |
| `prowl_call_tool` | Invoke any bank tool with wallet metering |
| `prowl_get_stats` | Session tokens, cost, tool counts |
| `prowl_generate_artifact` | PDF / PPTX / infographic from last report |
| `prowl_export_report` | Export report to markdown / HTML |
| `prowl_reset_session` | Clear session memory |

Legacy aliases: `prowl_test_tool` (= `prowl_call_tool`), `prowl_get_tool_info` (= `prowl_tool_info`).

Core tools shown — the full list of all 22 registered tools (sessions, schedules, playbooks, error feed) lives at https://prowl.chat/mcp/skill.md.

## Scoped API Keys

Keys support optional restrictions: allowed/denied tool categories, daily/total spend caps, IP allowlist. Create via `POST /api/mcp/keys` or MCP Home.

## Intelligence Modules (prowl_analyze output)

Market topology, positioning matrix, revenue mechanics, funnel intelligence, creative signals, market pulse, voice & vulnerability, strategic execution — delivered as one executive-ready report.

## Docs

- [Getting started](https://prowl.chat/getting-started/): connect any MCP client in five steps — sign up, generate a key, wire the client, verify, run the first report.
- [Running your first report](https://prowl.chat/docs/running-your-first-report/): per-tier duration and cost caps, the async poll pattern, the 30-minute timeout with resume, cancel semantics.
- [Billing and top-ups](https://prowl.chat/docs/billing-and-top-ups/): the prepaid wallet, $10/$50/$200 credit packs via Stripe, declined cards, receipts, refund policy.
- [Rate limits and errors](https://prowl.chat/docs/rate-limits-and-errors/): 300/min per IP, 120/min per key, JSON-RPC error codes -32001/-32002/-32003, 429 backoff.
- [Scheduling and webhooks](https://prowl.chat/docs/scheduling-and-webhooks/): daily/weekly/monthly cadence, private webhook triggers, retries, limits, the test path.
- [Cancellation and account deletion](https://prowl.chat/docs/cancellation-and-account-deletion/): how cancelling works at period end, and what happens to credit and data on deletion.
- [Docs index](https://prowl.chat/docs/): all reference guides in one place.

## Agent references

- [MCP skill doc](https://prowl.chat/mcp/skill.md): the full agent-facing tool reference — every tool, argument and response shape.
- [Agent install skill](https://prowl.chat/mcp/install.md): hand this to a coding agent and it wires up the client config and token file itself.
- [Agent skill manifest](https://prowl.chat/.well-known/agent-skills/prowl/SKILL.md): the well-known skill descriptor for agent runtimes.
- [MCP health](https://prowl.chat/mcp/health): liveness of the MCP endpoint.

## Use cases

- [Use cases index](https://prowl.chat/use-cases/): what teams build on top of the Prowl MCP.
- [Claude MCP server](https://prowl.chat/use-cases/claude-mcp-server/): add Prowl in Claude Code or Claude Desktop and Claude gains 448 live market-data tools.
- [Cursor MCP server](https://prowl.chat/use-cases/cursor-mcp-server/): one block in .cursor/mcp.json gives Cursor's agent the same 448 tools inside the editor.

## Optional

- [Homepage](https://prowl.chat/): product overview, pricing tiers, and the MCP quick start.
- [Contact](https://prowl.chat/contact/): reach the Prowl team.
- [Privacy policy](https://prowl.chat/privacy/): what data is collected and how it is handled.
- [Terms of service](https://prowl.chat/terms/): terms governing use of the platform.


---

# Full MCP tool reference

The complete agent-facing documentation, inlined from https://prowl.chat/mcp/skill.md

# Prowl MCP Server — AI Agent Skill

> **Protocol:** Model Context Protocol (MCP)
> **Server name:** `prowl_mcp`
> **Version:** 1.4.0

Prowl is **the MCP that turns any AI agent into a research analyst** — not a research tool, but the intelligence layer your agent connects to. It exposes **448 marketing intelligence API tools** (across DataForSEO, Majestic, Keywords Everywhere, SearchAPI, SerpAPI, web scraping, SEO, ads, AI, and utility providers) so your agent answers with real numbers instead of guesses, plus the full Prowl pipeline — multi-agent analysis, individual tool invocation, artifact generation, and session management — to any MCP-compatible client.

---

## Authentication

All requests to the MCP server require a **Bearer API key** in the `Authorization` header:

```
Authorization: Bearer prowl_<your_key>
```

API keys are generated from the Prowl web UI under **MCP Home → "Generate your token" (Step 1 of "Set up in 3 steps")** (or `POST /api/mcp/keys` / `POST /api/v1/keys` with JWT). Each key starts with the `prowl_` prefix followed by 32 hex characters (38 characters total).

### Scoped keys (optional)

When creating a key you may restrict:

| Field | Effect |
|-------|--------|
| `allowed_categories` | Allowlist (e.g. `["dataforseo", "web"]`); empty = all categories. Categories follow provider family: `dataforseo`, `seo`, `serpapi_serp`, `searchapi`, `ads`, `ai`, `web`, `utility`, `analyze` (DataForSEO = `dataforseo`, not `seo`). `prowl_analyze` needs `analyze` (or an empty allowlist) |
| `denied_categories` | Blocklist (e.g. `["ads"]`) |
| `daily_spend_limit_usd` | Max billed USD per UTC day for this key |
| `total_spend_limit_usd` | Lifetime spend cap for this key |
| `ip_allowlist` | Only accept requests from listed IPs |

Scoped keys enforce category and spend policy on `prowl_call_tool` **and** `prowl_analyze` (preflight, before any tool runs). Revoked keys → **401**; IP violations → **403**.

The following endpoints are publicly accessible without authentication:
- `/mcp/skill.md` — this document
- `/mcp/health` — server health check (returns JSON with status, version, MCP tool count, underlying API-tool count, cached-session count)

---

## Billing & Wallet

MCP HTTP transport uses **USD wallet billing** (not report quotas):

| Pool | Source | Expiry | Charge order |
|------|--------|--------|--------------|
| **Subscription** | Stripe plan renewal | Burns at period end | 1st |
| **Extra** | Top-up packs ($10 / $50 / $200) | Never expires | 2nd |

- **`prowl_call_tool`** — wallet preflight before invoke; response JSON includes `billing` (`estimated_cost_usd`, `actual_cost_usd`, `debited`, …)
- **`prowl_analyze`** — pre-flight wallet gate + post-query debit for aggregate tool spend
- New signups get **$5 starter credit** in the extra pool (`PROWL_STARTER_CREDIT_USD`, default `5`)
- Insufficient balance → tool error or gate block before expensive runs

**Inspect balance (JWT):**

```bash
curl -H "Authorization: Bearer <jwt>" https://prowl.chat/api/v1/wallet
```

**Public price catalog:**

```bash
curl https://prowl.chat/api/v1/tools/pricing?limit=50
```

**Top-up packs:** `GET /api/topup/packs`, `POST /api/checkout/topup` (JWT).

---

## Server URL

```
https://<your-prowl-host>/mcp
```

For local development via stdio transport:

```bash
python -m mcp_server
```

---

## Configuration

### Claude Desktop / Cursor (HTTP — Remote)

```json
{
  "mcpServers": {
    "prowl": {
      "url": "https://<your-prowl-host>/mcp",
      "headers": {
        "Authorization": "Bearer prowl_<your_key>"
      }
    }
  }
}
```

### Claude Desktop / Cursor (stdio — Local)

stdio is for local development from a cloned repo. Launch via `uv` so
dependencies resolve, and supply an LLM key in `env`. For hosted use, prefer
the HTTP transport above.

```json
{
  "mcpServers": {
    "prowl": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/0xDEV", "run", "python", "-m", "mcp_server"],
      "env": { "ANTHROPIC_API_KEY": "sk-..." }
    }
  }
}
```

---

## Tools (22 registered tools — 20 logical + 2 legacy aliases → 448 API tools)

> **Recommended flow for agents:** `prowl_search_tools` (or `prowl_list_tools`) → `prowl_tool_info` → `prowl_call_tool` (metered per invocation). Use `prowl_analyze` when you want a full strategy report in one shot (blocking), or the **session tools** (`prowl_start_session` → `prowl_session_status` → `prowl_get_session`) when you'd rather kick off a long deep-research run and poll for it asynchronously.

> **About `session_id`:** Most tools accept an optional `session_id` string. Pass the **same** value across consecutive calls and the server scopes the cached report, conversation history, and circuit-breaker state to that one conversation. Omit `session_id` and the server derives a key from your MCP client identity (`_meta.client_id`) or HTTP `mcp-session-id` / `x-session-id` header. The literal `__default__` is used as the last-resort fallback so stdio transports keep working.

### 1. `prowl_analyze`

Run a full competitive intelligence analysis. This is the core tool — it plans research, makes 20-400 API tool calls in parallel (depending on `execution_mode`: basic/deep/max), and synthesises a structured markdown report.

**Input:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string (3-2000) | Yes | Natural-language research query. Follow-ups about the previous report (translate, summarise, explain a section) are answered conversationally from the cached report — no need to resend the whole query. Also accepts a domain-less product/business idea ("I want to build a…", "validate this idea before I build it") for pre-launch idea validation — not only a competitor URL or domain. |
| `execution_mode` | `"basic"` \| `"deep"` \| `"max"` | No | `"basic"` (20-100 tool calls, ~30-90s, free) \| `"deep"` (40-300 calls, multi-competitor deep-dive + evidence verification, 3-5min, requires an active Exploit+ subscription) \| `"max"` (60-400 calls, adversarially-verified claims, 5-10min, requires Blackops+). Unauthorized deep/max auto-downgrade to basic with a notice. Default `"basic"`. |
| `session_id` | string (≤128) | No | Pin this call to a chat session for per-session memory (see *About `session_id`* above). |

**Example:**
```json
{
  "query": "Full competitor analysis for stripe.com vs square.com",
  "execution_mode": "deep",
  "session_id": "stripe-analysis-2026-05"
}
```

**Returns:** Full markdown report with SEO, ads, funnels, reviews, pricing, and market trends. On `deep`/`max` runs, extracted claims are cross-checked against tool evidence — refuted or low-confidence claims are flagged and coverage gaps are disclosed honestly rather than glossed over.

**Execution time:** 30 seconds to 5 minutes. The server emits periodic `progress` + `info` events every ~15s so Cloudflare/DigitalOcean proxies don't cut the long-running connection.

---

### 2. `prowl_list_tools`

List all 448 available API tools grouped by category.

**Input:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `category` | string | No | Filter by category (e.g. `"dataforseo"`, `"searchapi"`, `"serpapi_serp"`, `"web"`, `"seo"`, `"ads"`, `"ai"`, `"utility"`). Omit for all. |

**Returns:** JSON with tools grouped by category and total count.

---

### 3. `prowl_search_tools`

**Semantic** search across the 448-tool catalog with pagination — the fastest way to find a tool when you know *what* you want but not its exact name. Returns compact entries (name, use case, category, provider, top-level params) instead of full schemas, so it's cheap to page through. Follow with `prowl_tool_info` for the full input schema of a chosen tool.

**Input:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string (≤500) | No | Natural-language description (e.g. `"find competitor backlinks"`, `"scrape a webpage"`). Blank → browse the catalog top-down by category. |
| `limit` | int (1-50) | No | Max results per page (default 10). |
| `offset` | int (≥0) | No | Pagination offset; pass `next_offset` from the previous page. |
| `category` | string | No | Restrict to a category (`"web"`, `"seo"`, `"ads"`, `"ai"`, `"dataforseo"`, `"searchapi"`, `"serpapi_serp"`, `"utility"`). |
| `provider` | string | No | Restrict to a provider (e.g. `"DataForSEO"`, `"SpyFu"`, `"Exa"`). |

**Returns:** JSON `{ query, results[], total, limit, offset, next_offset, degraded, filters }`. `next_offset` is `null` on the last page; `degraded=true` indicates the fallback (empty query or unavailable index) returned a category browse.

---

### 4. `prowl_tool_info`

Get detailed information about a specific API tool, including its full JSON input schema.

> Legacy alias: `prowl_get_tool_info`

**Input:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tool_name` | string (1-200) | Yes | Exact tool name (e.g. `"dataforseo_serp_google_organic_live_advanced"`). |

**Returns:** JSON with tool name, description, category, and JSON Schema for parameters.

---

### 5. `prowl_call_tool`

Directly invoke a single API tool with **wallet metering**. Each call debits your USD balance (provider cost × markup). Use for production agent workflows that call specific data APIs.

> Legacy alias: `prowl_test_tool`

**Input:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tool_name` | string (1-200) | Yes | Tool name to invoke. |
| `params` | object | No | JSON parameters for the tool. Default: `{}`. |
| `session_id` | string (≤128) | No | Scope the invocation to a chat session (shares the same cache/circuit-breaker state as `prowl_analyze`). |

**Example:**
```json
{
  "tool_name": "extract_domain_from_url",
  "params": {"url": "https://www.example.com/pricing"}
}
```

**Returns:** JSON with `tool_name`, `success`, `data`, `error`, and `execution_time_ms`.

---

### 6. `prowl_get_stats`

Get current session statistics including token usage, cost estimate, tool call counts, and memory usage.

**Input:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `session_id` | string (≤128) | No | Scope stats to a specific chat session. |

**Returns:** JSON session statistics.

---

### 7. `prowl_generate_artifact`

Generate a visual artifact from the last analysis report. Requires a prior `prowl_analyze` call **on the same `session_id`**.

**Input:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `artifact_type` | `"infographic"` \| `"pdf"` \| `"pptx"` | Yes | Type of artifact. |
| `theme` | `"prowl"` \| `"prowl-gold"` \| `"prowl-light"` | No | Visual theme. Default: `"prowl"`. |
| `session_id` | string (≤128) | No | Must match the `session_id` used for the `prowl_analyze` call that produced the report. |

**Returns:** JSON with artifact type and file path.

---

### 8. `prowl_export_report`

Export the last analysis report to a file. Requires a prior `prowl_analyze` call **on the same `session_id`**.

**Input:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `format` | `"markdown"` \| `"html"` | No | Export format. Default: `"markdown"`. |
| `filepath` | string | No | Destination path. Auto-generated if omitted. |
| `session_id` | string (≤128) | No | Scope the export to a specific chat session. |

**Returns:** JSON with format and absolute file path.

---

### 9. `prowl_reset_session`

Reset the agent conversation, cached report, and circuit breakers. Use when switching research topics.

**Input:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `session_id` | string (≤128) | No | Scope the reset to a specific chat session. When omitted, resets the session identified by the MCP client. |

**Returns:** Confirmation message.

---

## Session tools (async chat sessions)

These four tools let an agent **drive analyses asynchronously** and read back
results by `session_id`. A session is the same chat-session row the web
dashboard shows, so work started over MCP is visible in the UI and vice versa.
Ownership is always enforced — a key can only see sessions belonging to its
user.

### 10. `prowl_start_session`

Start a competitive-intelligence analysis **in the background** and return
immediately with a `session_id`. The run continues on a detached server-side
task, so a dropped SSE stream (or an agent that stops polling) won't cancel it.

**Input:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string (3-2000) | Yes | Natural-language research query. |
| `execution_mode` | `"basic"` \| `"deep"` \| `"max"` | No | `"basic"` (~30-90s) \| `"deep"` (3-5min, requires an active Exploit+ subscription) \| `"max"` (5-10min, adversarially-verified, requires Blackops+). Unauthorized deep/max auto-downgrade to basic with a notice. Default: `"basic"`. |
| `title` | string (≤200) | No | Friendly session title (defaults to a query snippet). |

**Returns:** JSON `{session_id, status:"running", title, execution_mode, message}`.
Bills exactly like `prowl_analyze` (wallet preflight before the run, debit
after). Use `prowl_session_status` to poll.

**Example:**
```json
{"query": "Full competitor analysis for stripe.com vs square.com", "execution_mode": "deep", "title": "Stripe vs Square"}
```

---

### 11. `prowl_session_status`

Poll a started session. While running, returns live `progress` (0-1) and
`stats`; when finished, includes `status:"completed"` with the full `report`
(or `status:"failed"` with `error`). Falls back to the database for sessions
whose in-memory job has expired or that completed before a server restart.

**Input:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `session_id` | string (1-128) | Yes | The id returned by `prowl_start_session`. |

**Returns:** JSON `{session_id, status, progress?, stats?, report?, error?}` where
`status` ∈ `queued` / `running` / `completed` / `failed` / `not_found`.

---

### 12. `prowl_get_session`

Fetch the generated report (and optionally full message history) for a
specific session. Reads the persisted report from the database first, falling
back to the in-memory job result.

**Input:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `session_id` | string (1-128) | Yes | Session to read. |
| `include_messages` | boolean | No | Include the full user/assistant message history. Default: `false`. |

**Returns:** JSON `{session_id, status, report, report_available, messages?}`.

---

### 13. `prowl_list_sessions`

List the caller's chat sessions, newest first. Each entry carries a `status`
(`running` while a background analysis is in flight, otherwise
`completed` / `failed` / `empty`).

**Input:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer (1-200) | No | Max sessions to return. Default: `50`. |

**Returns:** JSON `{sessions:[{session_id, title, status, created_at, updated_at, message_count, tool_calls_count}], count, source}`.

---

## Playbook, scheduling & diagnostics tools

These six tools round out the wrapper surface: pick a fixed report shape, manage recurring background analyses, and inspect recent errors for your account. The scheduling and error-feed tools require an authenticated Prowl account (API key) — they return an `Error:` string otherwise.

### 14. `prowl_list_playbooks`

List the available report playbooks. A playbook is a fixed, persona-tuned set of report sections — pass its id as `playbook_id` to `prowl_analyze` to force that exact report structure instead of dynamic, query-driven section selection.

**Input:** None.

**Returns:** Markdown list of playbooks (id, title, target personas, what each covers, section count).

---

### 15. `prowl_schedule_create`

Register a saved analysis that runs automatically and stores the report.

**Input:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Natural-language research query to run on each fire. |
| `trigger_type` | `"interval"` \| `"webhook"` | No | `"interval"` runs on a `cadence` at `run_at_hour` (UTC). `"webhook"` returns a unique URL that runs the report when POSTed. Default: `"interval"`. |
| `execution_mode` | `"basic"` \| `"deep"` \| `"max"` | No | Resolved fresh against the account's subscription tier when the job actually fires (not at creation time) — deep/max auto-downgrade to basic if the required tier isn't active then. Default: `"basic"`. |
| `playbook_id` | string | No | Optional playbook id (see `prowl_list_playbooks`) to fix the report structure. |
| `cadence` | `"daily"` \| `"weekly"` \| `"monthly"` | Required when `trigger_type="interval"` | How often the schedule fires. |
| `run_at_hour` | int (0-23) | No | Hour of day (UTC) an interval schedule fires. Default: `8`. |

**Returns:** Confirmation with the schedule id (and a webhook URL when `trigger_type="webhook"`). Manage with `prowl_schedule_list` / `prowl_schedule_cancel` / `prowl_schedule_resume`.

---

### 16. `prowl_schedule_list`

List the caller's scheduled report runs.

**Input:** None.

**Returns:** Markdown list of schedules: id, active/paused state, trigger type, cadence + next-run time (or webhook), and query snippet.

---

### 17. `prowl_schedule_cancel`

Delete one of the caller's scheduled jobs.

**Input:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `job_id` | string | Yes | Id of the schedule to delete (from `prowl_schedule_list`). |

**Returns:** Confirmation message, or an error if no schedule with that id is owned by the caller.

---

### 18. `prowl_schedule_resume`

Re-activate a paused scheduled job (e.g. after topping up the wallet).

**Input:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `job_id` | string | Yes | Id of the schedule to resume. |

**Returns:** Confirmation message, or an error if no schedule with that id is owned by the caller.

---

### 19. `prowl_get_error_feed`

Recent errors for the caller's account: failed tools, billing, and actions. Read-only; scoped to your own account.

**Input:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `hours` | int (1-720) | No | Lookback window in hours. Default: `24`. |
| `source` | string | No | Filter by source: `"tool_error"`, `"action"`, `"tool_invocation"`, `"billing_outbox"`. |
| `tool_name` | string | No | Filter to errors from a specific tool. |
| `error_class` | string | No | Filter by class: `"network"`, `"server"`, `"auth"`, `"rate_limit"`, `"timeout"`, `"plan_denied"`, `"client"`, `"unknown"`. |
| `severity` | string | No | Filter by severity: `"alert"`, `"warn"`, `"info"`. |
| `limit` | int (1-200) | No | Max events to return. Default: `50`. |

**Returns:** Markdown list of matching error events (timestamp, severity, source, tool, error class, message), or a "no errors" message.

---

## Resources (3)

Resources provide read-only access to server state via `prowl://` URIs.

| URI | Description |
|-----|-------------|
| `prowl://tools` | Full catalog of all 448 API tools with schemas, grouped by category. |
| `prowl://stats` | Current session statistics snapshot. |
| `prowl://report` | Last generated analysis report (markdown). |

> Resources read from the **default** session cache because FastMCP's resource protocol has no per-call context. To inspect a specific session's state, call the `prowl_get_stats` tool with a `session_id` argument instead.

---

## Prompts (3)

Pre-built prompt templates for common research scenarios.

### `competitor_analysis`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `domain` | string | Yes | Target domain (e.g. `"example.com"`). |
| `focus_areas` | string | No | Comma-separated focus areas (e.g. `"SEO, pricing, ads"`). |

### `seo_audit`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `domain` | string | Yes | Target domain to audit. |

### `ad_creative_research`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `domain` | string | Yes | Target domain to research. |
| `platforms` | string | No | Comma-separated platforms (e.g. `"Facebook, Google, TikTok"`). |

---

## Workflows

### Basic Analysis Workflow

```
1. prowl_analyze(query="Competitor analysis for stripe.com", session_id="s1")
2. prowl_generate_artifact(artifact_type="pdf", theme="prowl", session_id="s1")
3. prowl_export_report(format="html", session_id="s1")
```

### Async Session Workflow (long deep-research, non-blocking)

```
1. prowl_start_session(query="Deep competitor analysis for stripe.com", execution_mode="deep")
                                          → {session_id, status:"running"}
2. prowl_session_status(session_id="...") → poll: running (progress) … → completed (report)
3. prowl_get_session(session_id="...", include_messages=true)  → durable report + history
   prowl_list_sessions()                  → see all your sessions and their status
```

### Tool Discovery Workflow (recommended)

```
1. prowl_search_tools(query="...")        → find tools by intent (or prowl_list_tools to browse)
2. prowl_tool_info(tool_name="...")       → check input schema + estimated cost
3. prowl_call_tool(tool_name="...", params={...})  → invoke with wallet debit
```

### Multi-Query Research Session

```
1. prowl_analyze(query="SEO audit for example.com", session_id="seo-job")
2. prowl_generate_artifact(artifact_type="infographic", session_id="seo-job")
3. prowl_reset_session(session_id="seo-job")
4. prowl_analyze(query="Ad creative research for example.com", session_id="ads-job")
5. prowl_export_report(format="markdown", session_id="ads-job")
```

---

## Error Handling

All tools return structured error messages prefixed with `"Error:"`. Common patterns:

| Error | Cause | Resolution |
|-------|-------|------------|
| `Error: Report limit reached for your account` | Legacy web chat quota (not MCP wallet) | Use MCP wallet / subscribe / top up |
| `Error: API key is not allowed to call tools in category` | Scoped key category restriction | Use a key with broader scopes or different tool |
| `Error: API key spend limit reached` | Per-key daily/total cap hit | Top up wallet or create key with higher limit |
| `Error: No report available` | Artifact/export called before analysis on this `session_id` | Run `prowl_analyze` with the same `session_id` first |
| `Error: Tool 'xyz' not found` | Invalid tool name | Use `prowl_list_tools` to find the correct name |
| `Error: Analysis failed — <ErrorType>: <message>` | Upstream API, network, or planner error | Retry the query; if it persists, call `prowl_reset_session` |

Transport-level errors: HTTP **401** (invalid/revoked key), **403** (IP not allowlisted), JSON-RPC **-32603** (internal).

---

## Session Behavior

The server keeps a **per-client `ProwlAPI` cache** keyed in this order:

1. Explicit `session_id` argument passed to the tool.
2. `_meta.client_id` populated by the MCP SDK from the calling client.
3. HTTP `mcp-session-id` or `x-session-id` request header.
4. The literal `__default__` (last-resort fallback for stdio transports / tests).

Each cached entry has its own `OrchestratorAgent`, last report, conversation history, and circuit-breaker state. Two callers with different `session_id`s do **not** share memory — Cursor window A and Cursor window B can run independent analyses concurrently.

Idle entries are swept after `PROWL_MCP_SESSION_TTL_SEC` seconds (default 7200 = 2h); the cache is bounded by `PROWL_MCP_MAX_SESSIONS` (default 64) with LRU eviction. `prowl_reset_session` evicts the entry immediately.

---

## Tool Categories

The 448 underlying API tools are organised into:

- **dataforseo** (~149) — SERP, keyword research, backlinks, domain analytics, On-Page, Content Analysis, Business Data
- **searchapi** (~100) — Specialised search engines: Google Ads Transparency, Maps, News, Trends, Scholar, YouTube, LinkedIn, Yandex, Baidu, Naver, Bing, Yahoo, DuckDuckGo, Walmart, Amazon, eBay, Etsy
- **serpapi_serp** (~57) — SerpAPI integrations: Google Lens, Reviews, Discover, Finance, Local, Direct Answers; Facebook profiles, X/Twitter timelines, Reddit, Pinterest, Instagram
- **seo** (~55) — SpyFu domain stats, PPC/SEO competitors, KOMBAT, kw rankings; Majestic TrustFlow/CitationFlow backlinks, ref domains, anchor text; Firecrawl scrape; SEO/PPC keyword research
- **web** (~19) — Web scraping, screenshots, niche-media/channel discovery, domain analysis, page extraction
- **ads** (~12) — Ad creative research, spend analysis, campaign data (Meta, Google, TikTok, LinkedIn)
- **ai** (~10) — AI-powered content analysis, summarisation, perplexity_chat
- **utility** (~6) — URL parsing, domain extraction, data formatting, validation

Use `prowl_list_tools(category="dataforseo")` to explore tools in a specific category. The exact tool count and category breakdown is dynamic and available live via `/mcp/health` and the `prowl://tools` resource.

---

## Rate Limits & Billing

- **`prowl_call_tool`** — wallet-gated; each invocation debits USD balance and is logged with `api_key_id` when using a scoped key
- **`prowl_analyze`** — wallet pre-flight gate + aggregate post-query debit; long runs emit heartbeat every ~15s (SSE keep-alive)
- Subscription tiers grant **USD credit bundles** per billing period (Exploit $60, Blackops $120, Syndicate $240); unused subscription balance burns at period end. `deep` execution_mode requires an active Exploit+ subscription; `max` requires Blackops+. A key without the required tier is auto-downgraded to `basic`, never rejected outright.
- Extra credits from top-up packs never expire
- The MCP API key validation cache trims to 256 entries on insertion (LRU when full)

---

## Agent REST API (JWT)

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/v1/wallet` | Dual-wallet balance |
| `GET` | `/api/v1/wallet/invocations` | Recent tool calls |
| `GET` | `/api/v1/usage/tools` | Alias for recent invocations |
| `GET` | `/api/v1/usage/summary` | Spend by day/category |
| `GET` | `/api/v1/tools/pricing` | Public catalog (`estimated_billed_usd`) |
| `POST` | `/api/v1/keys` | Create scoped MCP API key |
| `GET` | `/api/v1/keys` | List keys (v1 alias) |
| `DELETE` | `/api/v1/keys/{id}` | Revoke key (v1 alias) |
| `GET` | `/api/mcp/keys` | List keys |
| `DELETE` | `/api/mcp/keys/{id}` | Revoke key |

---

## Health Check

```bash
curl https://<your-prowl-host>/mcp/health
```

Returns JSON like:

```json
{
  "status": "ok",
  "server": "prowl_mcp",
  "version": "1.4.0",
  "transport": "streamable-http",
  "endpoint": "/mcp",
  "mcp_tool_count": 21,
  "mcp_tools": ["prowl_analyze", "prowl_list_tools", "prowl_search_tools", "prowl_start_session", "..."],
  "api_tool_count": 448,
  "cached_sessions": 0,
  "api_status": "lazy_pending",
  "tool_count": 21
}
```

| Field | Meaning |
|-------|---------|
| `status` | `"ok"` when MCP tools are registered, `"degraded"` otherwise |
| `mcp_tool_count` | Number of MCP tools (the `prowl_*` wrappers) |
| `api_tool_count` | Underlying provider tool count delegated to by the wrappers |
| `cached_sessions` | Current per-client `ProwlAPI` instances in the cache |
| `api_status` | `"lazy_pending"` (no session yet), `"ready"` (at least one warmed), or `"error: <details>"` |