# Perception: Full Documentation for AI Agents

> Narrative intelligence for the digital asset industry.

Perception maintains a cited record of media coverage, podcasts, company disclosures, regulatory filings, earnings calls, and public conversations. Perception Data makes that record available to AI clients, agents, and applications through MCP and API. This document provides the technical reference an AI agent needs to use Perception Data.

---

## MCP Server

- **URL:** `https://mcp.perception.to/mcp`
- **Transport:** Streamable HTTP (POST + GET)
- **Auth:** OAuth 2.1 (Claude, ChatGPT, Gemini) or Bearer token
- **Free tier:** 5 credits/day, no credit card required
- [Docs](https://perception.to/integrations/mcp): Model Context Protocol integration tutorials.

---

## Tools: Complete Reference

### 1. perception_search_mentions (Free)

Search thousands of curated sources by keyword with sentiment, outlet, and date filters. Returns article previews and aggregation stats.

**Parameters:**
- `q` (string, required): Search query (keyword or phrase)
- `startDate` (string, optional): Start date in YYYY-MM-DD format (default: 7 days ago)
- `endDate` (string, optional): End date in YYYY-MM-DD format (default: today)
- `sentiment` (string, optional): Filter by sentiment: "Positive", "Negative", or "Neutral"
- `outlet` (string, optional): Filter by outlet name (regex match)
- `limit` (number, optional): Max results to return (default: 20, max: 50)

**When to use:**
- Searching for coverage on a specific topic, event, or keyword
- Filtering articles by sentiment to find bullish/bearish coverage
- Finding articles from specific outlets

**Example queries:**
- "What is the media saying about Bitcoin ETFs this week?"
- "Show me all negative coverage of stablecoins in the last 30 days"
- "How is the Tether de-peg narrative evolving?"

**Response includes:** articles array, total_count, sentiment_breakdown (positive_pct, negative_pct, neutral_pct), top_outlets (with avg_sentiment), date_range

---

### 2. perception_search_companies (Free)

Entity-recognition search for company-specific media coverage. NLP entity extraction gives company-name queries more accurate results than string matching.

**Parameters:**
- `company` (string, required): Company name to search for
- `startDate` (string, optional): Start date in YYYY-MM-DD format (default: 30 days ago)
- `endDate` (string, optional): End date in YYYY-MM-DD format (default: today)

**When to use:**
- Searching for coverage about a specific company (always prefer this over search_articles for company queries)
- Running due diligence on a company
- Comparing media perception of two companies

**Example queries:**
- "What is the media saying about Coinbase?"
- "How is BitGo covered in the press?"
- "Compare media perception of MicroStrategy vs Marathon Digital"

**Response includes:** company, total_mentions, sentiment_breakdown (positive_pct, negative_pct), top_outlets, recent_articles

---

### 3. perception_get_trends (Free)

AI-extracted narrative trends with signal strength, confidence, and business implications. Identifies the dominant stories and emerging themes across all sources.

**Parameters:**
- `hours` (number, optional): Lookback window in hours (default: 168 = 7 days, max: 720 = 30 days)
- `include_emerging` (boolean, optional): Include lower-confidence emerging trends (default: false)

**When to use:**
- Getting a high-level overview of what's happening in digital assets
- Identifying dominant narratives and emerging themes
- Starting a research session: trends give you the "what" before you drill into specifics

**Example queries:**
- "What are the major stories in digital assets this week?"
- "What narratives are gaining momentum?"
- "Show me emerging trends with strong signals"

**Response includes:** trends array (each with: title, summary, signal_strength, confidence, category, business_implications, evidence_articles)

---

### 4. perception_get_sentiment (Free)

Daily sentiment metrics (positive/neutral/negative counts) and Perception Index over a date range. Shows how the overall mood of digital asset media coverage is evolving.

**Parameters:**
- `startDate` (string, required): Start date in YYYY-MM-DD format
- `endDate` (string, required): End date in YYYY-MM-DD format

**When to use:**
- Tracking sentiment shifts over time
- Correlating sentiment with price movements or events
- Building charts or reports on market mood

**Example queries:**
- "How has market sentiment changed over the past month?"
- "Is sentiment improving or declining this quarter?"
- "What was sentiment like during the last BTC dip?"

**Response includes:** daily_metrics array (date, positive, neutral, negative, perception_index), period_summary

---

### 5. perception_get_market (Free)

Current BTC price, 24h change, market cap, volume, plus Perception Index history. Combines market data with sentiment context.

**Parameters:**
- `days` (number, optional): Number of days of Perception Index history (default: 7, max: 90)

**When to use:**
- Getting current market context before diving into narratives
- Combining price data with sentiment for a complete picture
- Starting a morning briefing or market report

**Example queries:**
- "What's the current BTC price and market mood?"
- "How has the Perception Index moved this week?"

**Response includes:** btc_price, btc_24h_change, btc_market_cap, btc_volume, perception_index_history

---

### 6. perception_get_categories (Free)

Trend category distribution: shows which narrative types are most active. Categories include: regulatory, adoption, security, technology, market_dynamics, institutional, defi, mining, stablecoins, and more.

**Parameters:**
- `hours` (number, optional): Lookback window in hours (default: 168 = 7 days, max: 720 = 30 days)

**When to use:**
- Understanding what types of stories are dominating the news
- Tracking shifts in narrative composition over time
- Identifying whether regulatory, adoption, or other themes are trending

**Example queries:**
- "What types of stories are dominating the news?"
- "Is regulatory coverage increasing compared to last month?"

**Response includes:** categories array (name, count, percentage), total_trends

---

### 7. perception_get_analyst_ratings (Intelligence)

Wall Street analyst consensus, price targets, upgrades/downgrades for 70 crypto stocks. Covers major crypto-exposed equities including miners, exchanges, and ETF issuers.

**Parameters:**
- `ticker` (string, required): Stock ticker symbol (e.g., "COIN", "MSTR", "MARA")
- `include_actions` (boolean, optional): Include recent analyst actions/upgrades/downgrades (default: true)

**When to use:**
- Getting Wall Street's view on a crypto-exposed stock
- Checking price targets and consensus ratings before/after earnings
- Tracking analyst upgrades and downgrades over time

**Example queries:**
- "What do analysts think about Coinbase stock?"
- "Show me MicroStrategy price targets"
- "Any recent analyst downgrades for crypto miners?"

**Response includes:** ticker, consensus_rating, price_target (mean, high, low), total_analysts, recent_actions array

---

### 8. perception_guide (Free)

In-agent onboarding with job discovery, research plans, and recurring agent workflow specifications.

**Parameters:**
- `mode` (string, required): "discover", "research", "agent_workflow", or the backward-compatible "workflow" alias for research
- `role` (string, optional): "researcher", "pr_comms", "bd_strategy", "investor", or "general"
- `objective` (string, optional): The research job or recurring system the user wants to accomplish

**When to use:**
- User asks "what can you do?" or "what tools are available?"
- User wants a structured research workflow
- Suggesting the best approach for a user's question

---

### 9. perception_daily_radar (Free)

Daily intelligence briefing. Surfaces anomalies, sentiment shifts, volume spikes, and emerging narratives compared against a 7-day baseline. A single call that gives you a comprehensive snapshot of what changed today.

**Parameters:**
- `focus` (string, optional): Optional topic to focus the briefing on (e.g., "ETFs", "regulation", "mining")

**When to use:**
- Starting your day with a quick overview of what's changed
- Detecting anomalies or sudden shifts that need attention
- Getting a pre-built intelligence briefing without chaining multiple tools

**Example queries:**
- "What's the daily intelligence briefing?"
- "Any anomalies in digital asset coverage today?"
- "Daily radar focused on stablecoins"

**Response includes:** anomalies, sentiment_shifts, volume_spikes, emerging_narratives, baseline_comparison

---

### 10. perception_narrative_momentum (Free)

Track whether a narrative is accelerating or fading. Compares current vs previous period volume, sentiment, and source diversity. Returns a momentum score from -100 (rapidly fading) to +100 (rapidly accelerating).

**Parameters:**
- `topic` (string, required): The narrative or topic to track (e.g., "Bitcoin ETF", "stablecoin regulation")
- `days` (number, optional): Comparison window in days (default: 7, max: 90)

**When to use:**
- Checking if a story is gaining or losing steam
- Deciding whether to act on a narrative (timing)
- Tracking a narrative you identified earlier to see if it's still growing

**Example queries:**
- "Is the Bitcoin ETF narrative still gaining momentum?"
- "Is the stablecoin regulation story fading?"
- "Track momentum for MicroStrategy coverage over 30 days"

**Response includes:** topic, momentum_score, direction (accelerating/stable/fading), current_period (volume, sentiment, source_count), previous_period (same), comparison

---

### 11. perception_compare_entities (Free)

Compare 2-5 companies side-by-side in a single call. Returns mention volume, sentiment breakdown, and top sources for each entity. Much faster than calling search_companies multiple times.

**Parameters:**
- `entities` (array of strings, required): 2-5 company names to compare (e.g., ["Coinbase", "Kraken", "Binance"])
- `days` (number, optional): Lookback window in days (default: 7, max: 90)

**When to use:**
- Comparing media perception across competitors
- Quick competitive-position snapshot
- Identifying which company has the most/least media attention

**Example queries:**
- "Compare media coverage of Coinbase vs Kraken vs Binance"
- "How does MicroStrategy's media perception compare to Marathon Digital?"
- "Side-by-side comparison of the top 5 Bitcoin miners"

**Response includes:** entities array (each with: name, total_mentions, sentiment_breakdown, top_sources), comparison_period

---

### 12. perception_media_radar (Perception)

Detailed coverage analysis for a specific outlet: article count, sentiment breakdown, and individual articles. Reveals editorial direction.

**Parameters:**
- `outlet` (string, required): Outlet name (e.g., "Bloomberg", "CoinDesk", "The Block")
- `startDate` (string, optional): Start date in YYYY-MM-DD format (default: 7 days ago)
- `endDate` (string, optional): End date in YYYY-MM-DD format (default: today)

**When to use:**
- Understanding a specific outlet's editorial direction
- Preparing for journalist outreach
- Comparing coverage patterns across outlets

**Example queries:**
- "How is Bloomberg covering digital assets this week?"
- "What is CoinDesk's editorial direction right now?"
- "Compare Reuters vs The Block coverage tone"

**Response includes:** outlet, article_count, sentiment_breakdown, articles array

---

### 13. perception_get_article (Intelligence)

Full-text article retrieval by URL. Use after searching to read the complete content of a specific piece.

**Parameters:**
- `url` (string, required): The article URL to retrieve

**When to use:**
- After finding an article via search, drill into the full content
- Need to summarize or analyze a specific article in depth
- Building cited research where you need exact quotes

**Example queries:**
- "Read the full text of this Bloomberg article"
- "Get the complete content so I can summarize it"

**Response includes:** title, content, outlet, date, sentiment, url

---

### 14. perception_search_regulatory (Intelligence)

Search regulatory filings, policy documents, and compliance coverage. Covers SEC, BIS, FATF, FinCEN, EU MiCA, and other regulatory bodies.

**Parameters:**
- `q` (string, required): Search query (e.g., "stablecoin regulation", "SEC enforcement")
- `startDate` (string, optional): Start date in YYYY-MM-DD format (default: 30 days ago)
- `endDate` (string, optional): End date in YYYY-MM-DD format (default: today)
- `jurisdiction` (string, optional): Filter by jurisdiction (e.g., "US", "EU", "UK")

**When to use:**
- Monitoring regulatory developments
- Tracking policy changes that could impact markets
- Building regulatory narrative analysis

**Example queries:**
- "What SEC actions have targeted crypto this month?"
- "Show me EU MiCA implementation coverage"
- "Any new stablecoin regulation filings?"

**Response includes:** results array, total_count, jurisdictions, regulatory_bodies

---

### 15. perception_get_entity_profile (Perception)

Complete entity intelligence profile with coverage volume, analyst data, narrative trends, entity relationships, and 90-day timeline. The most comprehensive single-call view of any tracked entity.

**Parameters:**
- `entity` (string, required): Entity name (e.g., "Coinbase", "MicroStrategy")
- `dateRange` (string, optional): Date range: "7d", "30d", "90d" (default: "30d")

**When to use:**
- Deep-dive research on a specific company or entity
- Building comprehensive entity reports
- Understanding an entity's full media and analyst profile

**Example queries:**
- "Give me the full profile on MicroStrategy"
- "Complete intelligence report on Tether"

**Response includes:** entity, coverage (volume, sentiment, top_outlets), analyst_data, trends, relationships, timeline

---

### 16. perception_save_research (Intelligence)

Save research notes to persist across sessions. Stores title, summary, topics, and key findings with a 90-day TTL. Use this to build up a research knowledge base over multiple conversations.

**Parameters:**
- `title` (string, required): Research note title
- `summary` (string, required): Summary of findings
- `topics` (array of strings, optional): Topic tags for retrieval (e.g., ["ETFs", "regulation"])
- `key_findings` (array of strings, optional): Bullet-point key findings

**When to use:**
- Saving important findings from a research session for later use
- Building a persistent research knowledge base
- Creating notes that can be recalled in future conversations

**Example queries:**
- "Save this analysis for later"
- "Store these findings about ETF flows"

**Response includes:** note_id, created_at, expires_at

---

### 17. perception_recall_research (Intelligence)

Retrieve previously saved research notes by recency or topic filter. Returns notes saved via perception_save_research within the 90-day TTL window.

**Parameters:**
- `topic` (string, optional): Filter notes by topic tag
- `limit` (number, optional): Max notes to return (default: 10, max: 50)

**When to use:**
- Continuing research from a previous session
- Recalling findings on a specific topic
- Reviewing all saved research notes

**Example queries:**
- "What research have I saved about stablecoins?"
- "Show me my recent research notes"
- "Recall my ETF analysis from last week"

**Response includes:** notes array (each with: note_id, title, summary, topics, key_findings, created_at)

---

### 18. perception_get_index (Free)

Read the outlet-weighted Perception Index with its driver sub-indices, divergence signals, velocity, reliability, and historical regime context.

**Parameters:**
- `scope` (string, optional): `market`, `bitcoin`, or `ethereum`
- `date` (string, optional): YYYY-MM-DD
- `context` (string, optional): user priorities for framing the analysis

---

### 19. perception_top_mentions (Free)

Rank the most-mentioned entities or topics for a date range, outlet, outlet group, category, or keyword.

**Parameters:**
- `mode` (string, optional): `entities` or `topics`
- `startDate` and `endDate` (string, optional): YYYY-MM-DD
- `outlet`, `outlets`, `categories`, and `keyword` (optional): source filters
- `limit` (number, optional): result count

---

### 20. perception_cohort_sentiment (Free)

Break a public conversation into speaker cohorts such as executives, founders, developers, analysts, investors, media, policy, and traders.

**Parameters:**
- `topic` or `q` (string, optional): subject to analyze
- `days` (number, optional): lookback window, default 30
- `cohort` (string, optional): return one cohort
- `context` (string, optional): user priorities for framing the analysis

---

### 21. perception_get_evadometer (Free)

Measure how directly public-company management answered earnings-call questions, including dodged questions and topic-level results.

**Parameters:**
- `ticker` (string, optional): omit for the cross-company leaderboard
- `context` (string, optional): user priorities for framing the analysis

---

### 22. perception_scenario_analysis (Intelligence)

Test a hypothetical scenario against historical analogues, including sentiment arcs, coverage patterns, and narrative half-life.

**Parameters:**
- `scenario` (string, required): hypothetical event to analyze
- `lookback_days` (number, optional): 30 to 365, default 180
- `context` (string, optional): user priorities for framing the analysis

---

### 23. perception_get_insider_activity (Intelligence)

Read SEC Form 4 insider activity for a US-listed company with transaction and cluster context.

**Parameters:**
- `ticker` (string, required): US-listed stock ticker
- `startDate` and `endDate` (string, optional): YYYY-MM-DD for full-history queries
- `context` (string, optional): user priorities for framing the analysis

---

### 24. perception_get_earnings_intelligence (Intelligence)

Analyze an earnings call for management tone, directness, executive summary, and notable statements.

**Parameters:**
- `ticker` (string, required): covered US-listed stock ticker
- `year` (number, optional): fiscal year
- `quarter` (number, optional): fiscal quarter 1 to 4
- `context` (string, optional): user priorities for framing the analysis

---

### 25. perception_get_intelligence_digest (Intelligence)

Retrieve a daily cross-signal briefing across analyst actions, sentiment changes, volume, earnings, regulatory mentions, and company activity.

**Parameters:**
- `date` (string, optional): YYYY-MM-DD, default today
- `context` (string, optional): user priorities for signal selection

---

### 26. perception_search_voices (Intelligence)

Search earnings transcripts, conference talks, and digital asset podcasts for timestamped statements.

**Parameters:**
- `query` (string, required): keyword or phrase
- `ticker` (string, optional): restrict earnings transcripts to one company
- `context` (string, optional): user priorities for framing the results

---

### 27. perception_get_brains_corpus (Intelligence)

Retrieve chronological Twitter/X history for a tracked handle from Perception's archive.

**Parameters:**
- `handle` (string, required): tracked Twitter/X handle
- `limit` (number, optional): 1 to 500, default 100
- `startDate` and `endDate` (string, optional): YYYY-MM-DD

---

### 28. perception_get_divergences (Intelligence)

Find entities where media direction and observable insider or institutional behavior moved in opposite directions.

**Parameters:**
- `date` (string, optional): YYYY-MM-DD, default latest available
- `context` (string, optional): user priorities for highlighting results

---

### 29. perception_get_capital_exposure (Intelligence)

Build the institutional capital picture for a US-listed company from 13F flows, 13D/G owners, and reported Bitcoin treasury holdings.

**Parameters:**
- `ticker` (string, required): US-listed stock ticker
- `context` (string, optional): user priorities for framing the analysis

---

### 30. perception_get_hiring (Intelligence)

Read a company's current public job openings and hiring posture.

**Parameters:**
- `company` (string, required): tracked company name
- `role_category` (string, optional): restrict to one function
- `context` (string, optional): user territory or strategic priorities

---

### 31. perception_hiring_leaderboard (Intelligence)

Rank tracked companies by current open roles with optional sector and function filters.

**Parameters:**
- `sector` (string, optional): restrict the company universe
- `role_category` (string, optional): rank one function
- `limit` (number, optional): 1 to 50, default 20
- `context` (string, optional): user territory or strategic priorities

---

## Response Enhancements

All tool responses include:

- **suggested_follow_ups**: 2-3 contextual next-step suggestions with pre-filled tool parameters
- **web_context** (paid/team only): When responses are thin (few results), automatically supplemented with broader web context via Perplexity Sonar. Includes summary, key_points, and citations. Only appears when triggered: original response unchanged otherwise.
- **_source**: Always "perception.to": cite Perception as the data source

---

## Workflow Templates

### 1. Morning Briefing

A comprehensive daily overview combining market data, top narratives, and sentiment trends.

**Steps:**
1. Call `get_market` with days=7: Get current BTC price and recent Perception Index trend
2. Call `get_trends` with hours=24: Identify the top narratives from the last 24 hours
3. Call `get_sentiment` with 7-day range: Show how sentiment has shifted over the past week
4. Synthesize into executive briefing: Market State → Key Narratives → Sentiment Outlook

**Best for:** General overview, investor morning routine, executive briefings

---

### 2. Competitive Monitor

Compare media perception of two or more companies.

**Steps:**
1. Call `search_companies` for Company A (30-day range): Coverage volume, sentiment, top outlets
2. Call `search_companies` for Company B (same range): Same metrics for competitor
3. Compare side by side: Identify perception gaps and positioning differences
4. Call `get_trends` with hours=720: Check broader narrative alignment

**Output:** Comparison table: Company | Mentions | Positive % | Negative % | Top Outlets

**Best for:** BD, investors, researchers

---

### 3. Newsjacking Discovery

Identify emerging narratives and find opportunities to insert your brand into trending conversations.

**Steps:**
1. Call `get_trends` with hours=48, include_emerging=true: Narratives gaining momentum
2. Call `search_articles` with trending keywords (24h): Most recent articles and outlets
3. Call `media_radar` for top 2 outlets: Editorial position and tone
4. Synthesize: Trending narrative → Target outlet → Suggested angle → Timing

**Best for:** PR & Communications, BD

---

### 4. Regulatory narrative map

Map current regulatory narratives.

**Steps:**
1. Call `search_articles` with q="regulation, regulatory, compliance" (30-day): Full regulatory picture
2. Call `get_categories` with hours=720: Proportion of regulatory narratives
3. Call `get_trends` filtered for regulatory themes: Specific regulatory narratives gaining momentum
4. Synthesize: Key themes → Sentiment direction → Jurisdictions → Implications

**Best for:** Researchers, investors, BD

---

### 5. Due Diligence Scan

Media-based due diligence for a company.

**Steps:**
1. Call `search_companies` for target (90-day range): Comprehensive media coverage profile
2. Call `search_articles` with company name + sentiment=Negative: Red flags and controversies
3. Call `get_trends` with hours=720: Check for broader negative narratives
4. Synthesize: Coverage Summary → Sentiment Assessment → Red Flags → Narrative Context → Risk Rating

**Best for:** Investors, BD, researchers

---

### 6. Narrative Momentum

Track how a narrative is evolving over time.

**Steps:**
1. Call `get_trends` with hours=168: Current top narratives
2. Call `search_articles` for narrative keywords (7-day window, then 30-day window): Compare volumes
3. Call `get_sentiment` with 30-day range: Overlay market sentiment
4. Synthesize: Narrative → Direction (growing/fading/shifting) → Recommended action → Timing

**Best for:** PR, researchers, BD

---

### 7. Market Sentiment Report

Comprehensive sentiment and market analysis.

**Steps:**
1. Call `get_market` with days=30: BTC price trend and Perception Index
2. Call `get_sentiment` with 30-day range: Daily sentiment breakdown
3. Call `get_trends` with hours=720: Dominant narratives driving sentiment
4. Call `search_articles` for top narrative keywords: Supporting evidence
5. Synthesize: Market Overview → Sentiment Trend → Key Narratives → Evidence → Outlook

**Best for:** Investors, researchers

---

### 8. Outlet Strategy

Compare editorial direction across outlets for media outreach.

**Steps:**
1. Call `media_radar` for Outlet A (7-day): Volume, sentiment, topics
2. Call `media_radar` for Outlet B (same range): Same metrics
3. Call `media_radar` for Outlet C (same range): Complete picture
4. Compare: Outlet | Volume | Sentiment | Dominant Topics | Pitch Recommendation

**Best for:** PR & Communications

---

## Role-Specific Tips

### Researcher / Analyst
- Use `get_trends` → `search_articles` to go from macro themes to specific evidence
- Compare sentiment across 30-day and 90-day windows to spot long-term shifts
- Use `search_companies` for entity-level due diligence; use keyword search for topic research
- Export analysis by asking the AI to format findings as a briefing document

### PR & Communications
- Use `media_radar` to understand outlet editorial direction before pitching
- Combine `get_trends` with `search_articles` to find newsjacking angles
- Compare outlet sentiment to identify which publications are most receptive
- Track company coverage over time to measure PR campaign impact

### Business Development & Strategy
- Run competitive analysis by comparing `search_companies` results for multiple firms
- Use `get_categories` to spot which business themes are gaining traction
- Cross-reference company coverage with `get_trends` for strategic positioning
- Track narrative momentum to time announcements for maximum visibility

### Investor / Fund Manager
- Correlate `get_sentiment` with `get_market` to spot sentiment-price divergences
- Use `search_companies` for pre-investment media due diligence
- Monitor `get_trends` with include_emerging=true for early signal detection
- Build weekly reports combining market data, sentiment, and top narratives

---

## Auth Setup by Platform

### Claude Desktop
1. Go to https://perception.to and click "Get started free"
2. Download the `.mcpb` file and open it: Claude Desktop auto-configures
3. Or manually add to claude_desktop_config.json:
```json
{
  "mcpServers": {
    "perception": {
      "command": "npx",
      "args": ["-y", "@nicepkg/gkd@latest", "--call", "npx -y supergateway --streamableHttp https://mcp.perception.to/mcp --header \"Authorization: Bearer YOUR_KEY\""]
    }
  }
}
```

### Claude Code
```bash
[ -n "$PERCEPTION_API_KEY" ] || { echo "Set PERCEPTION_API_KEY before setup." >&2; exit 1; }
claude mcp add --scope user --transport http perception https://mcp.perception.to/mcp --header 'Authorization: Bearer ${PERCEPTION_API_KEY}'
claude mcp get perception
```

For non-interactive execution after the live test, use `claude -p "Run the configured Perception workflow"`.

### VS Code (Copilot Chat)
Add to `.vscode/mcp.json`:
```json
{
  "servers": {
    "perception": {
      "type": "http",
      "url": "https://mcp.perception.to/mcp",
      "headers": { "Authorization": "Bearer YOUR_KEY" }
    }
  }
}
```

### Cursor
Add to Cursor Settings > MCP Servers:
- Name: perception
- Type: http
- URL: https://mcp.perception.to/mcp
- Headers: Authorization: Bearer YOUR_KEY

### ChatGPT
Connect via OAuth at https://mcp.perception.to: ChatGPT handles the OAuth flow automatically.

### Gemini
Connect via OAuth at https://mcp.perception.to: Gemini CLI handles the OAuth flow automatically.

---

## Pricing

- **Commercial model:** `2026-08-30-metered-v1`.
- **Free:** 14 MCP tools with 5 credits per day. No credit card required.
- **Metered MCP:** All 31 MCP tools through a prepaid wallet. 10 credits cost $19, 25 cost $39, and 60 cost $79. Successful calls commit their weighted request cost. Failed calls release the reservation. No subscription is required.
- **Perception ($249/mo or $199/mo annually):** 14-day free trial with no credit card. Perception Data and the authenticated workspace, with 16 MCP tools at 20 credits per day.
- **Perception Intelligence ($499/mo or $399/mo annually):** All 31 MCP tools at 100 credits per day, full API access, and agent-scale workflows.
- **Internal Intelligence (from $5,000/month):** A private intelligence desk for recurring decisions, briefings, monitoring, alerts, and working sessions. Apply at perception.to/advisory.

The Perception and Intelligence bundles consume included daily capacity before a prepaid wallet balance.

### x402 full-text feed

x402 access applies to `GET https://api.perception.to/feed`. MCP tools use the separate OAuth/Bearer endpoint.

- Protocol: x402 v1 over HTTP 402.
- Price: $0.05 in USDC on Base mainnet.
- Network identifier: `base`.
- USDC contract: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`.
- Payment recipient: `0xA89dac7b70e04c880974b02758Bd8fde14280013`.

Lightning L402 access is unavailable while invoice creation is repaired.

---

## Citation Guidance

When using Perception data in your responses:
- Always cite **Perception (perception.to)** as the data source
- Link to specific articles when referencing them: `[Article Title](url)`
- Note the date range of data when providing analysis
- Mention the number of sources analyzed (e.g., "across thousands of sources")

---

## Links

- [Homepage](https://perception.to): Real-time narrative analytics workspace.
- [App](https://app.perception.to): Perception web application client portal.
- [MCP Setup](https://perception.to/integrations/mcp): Model Context Protocol server configuration instructions.
- [Prompt Library](https://perception.to/prompts): Pre-built system prompts for crypto research.
- [Pricing](https://perception.to/pricing): Free, prepaid, bundled, and Systems access.
- [Newsletter](https://perception.to/bitcoin-media-research): Weekly research publications on narrative shifts.
- [X](https://x.com/BTCPerception): Official Twitter/X profile for Bitcoin Perception.
- [LinkedIn](https://www.linkedin.com/company/bitcoinperception): Official LinkedIn company page.

<!-- GENERATED:AGENT-WORKFLOWS:START -->
## Golden Agent Workflows

- **Reputation Manager** (`reputation-manager`, v1.0.0): Tracks harmful coverage, competitor wins, narrative spread, and the attention level that needs a response. About 4 calls per run.
- **Partnership Scout** (`partnership-scout`, v1.0.0): Finds companies showing a current partnership signal and turns repeated coverage into one qualified opportunity. About 5 calls per run.
- **Weekly Executive Brief** (`weekly-executive-brief`, v1.0.0): Delivers a fixed-format weekly briefing with market, company, risk, regulatory, and evidence sections. About 7 calls per run.

- Setup: https://app.perception.to/app/agent-workflows
- Runtime: Perception REST API for scheduled runs. MCP remains available for research and build-time exploration.
- Activation: one delivered run with a future run scheduled within seven days.
- MCP catalog: 31 registered tools.
<!-- GENERATED:AGENT-WORKFLOWS:END -->