Perigon MCP Server

Perigon

Perigon is a news intelligence API providing real-time access to articles from 200,000+ sources, AI-clustered stories, summaries, semantic search, Wikipedia knowledge, and entity databases (650k+ people, companies, 230k+ journalists).

Endpoints

Query Syntax

The q parameter supports:

• Boolean operators: AND, OR, NOT
• Exact phrases: "climate change"
• Wildcards: * (multiple chars), ? (single char)
• Combining: "electric vehicles" AND (Tesla OR Rivian) NOT recalls

Key Filtering Patterns

• Date range: from/to (publication date, ISO 8601 or yyyy-mm-dd), addDateFrom/addDateTo (ingestion date)
• Source quality: sourceGroup = top10, top25, top50, top100, top25tech, top25crypto
• Categories: Tech, Politics, Sports, Business, Finance, Entertainment, Health, Science, World, Lifestyle
• Entities: personName, companySymbol, companyDomain, journalistId, personWikidataId
• Sentiment: positiveSentimentFrom/To, negativeSentimentFrom/To (0.0-1.0)
• Deduplication: showReprints=false removes wire-service copies (recommended for most use cases)
• Exclude filters: Prefix any filter with exclude (e.g. excludeCategory, excludeTopic, excludeSource)
• Article by ID: Use articleId filter on /v1/articles/all (no separate GET-by-ID endpoint)

Pagination

• page starts at 0, size controls results per page (default 10, max varies by endpoint)
• showNumResults=true returns total count (adds slight latency)
• Topics endpoint returns {total, data} shape; all other endpoints return {status, numResults, results|articles}
• Iterate pages for bulk data collection

Rate Limits

Exceeding rate limits returns HTTP 429. Plan-restricted endpoints return HTTP 403.

Workflow Patterns

1. Headline monitoring: Search stories with sourceGroup=top100 + sortBy=date for latest clustered headlines
2. Story deep-dive: Search stories → get clusterId → search articles with clusterId for all coverage
3. Story tracking: Get story history with clusterId to see how a story evolved over time with changelogs
4. Company intelligence: Search companies to resolve identity → search articles with companySymbol
5. Journalist research: Search journalists → get journalist ID → search articles with journalistId
6. Daily briefing: Summarize news with date range and topic/company filters (Plus+ plan)
7. Semantic research: Vector search news for intent-based queries + vector search wiki for background (Business plan)
8. Topic discovery: Search topics to find available topics → use as filters in article/story searches
9. Source evaluation: Search sources to compare bias ratings, traffic, and coverage patterns
10. Entity enrichment: Search people/companies to get Wikidata IDs → use as precise filters in article searches

Data Model

• Articles: title, content, URL, pubDate, addDate, sentiment (positive/negative/neutral 0-1), entities, categories, topics, source metadata, keywords with weights, clusterId, reprint status, summary, shortSummary
• Stories: AI-generated name, summary, shortSummary, keyPoints, sentiment, uniqueCount/reprintCount/totalCount, topPeople, topCompanies, topTopics, topCategories, topCountries, topLocations
• Story History: clusterId, createdAt, triggeredAt, summary, shortSummary, changelog, keyPoints, questions with AI answers
• People: wikidataId, name, gender, dateOfBirth, dateOfDeath, description, aliases, occupation, position, politicalParty, image, abstract
• Companies: id, name, altNames, domains, symbols, industry, sector, CEO, fullTimeEmployees, revenue, address/city/state/country, globalRank, monthlyVisits, webResources, isEtf/isFund/isAdr
• Journalists: id, name, fullName, headline, description, title, locations, topTopics, topSources, topCategories, avgMonthlyPosts, twitterHandle
• Sources: id, domain, name, altNames, description, avgMonthlyPosts, paywall, location, topCategories, topTopics, topCountries, avgBiasRating, adFontesBiasRating
• Topics: id, name, labels (category + subcategory)
• Wikipedia: wikiPageId, wikiTitle, url, summary, sections (heading + content), wikidataId, wikidataInstanceOf, topImage, redirectTitles

Gotchas

• Date params use from/to (not from_date/to_date) in the API; the tools handle this mapping
• Vector search endpoints require POST with JSON body, not GET with query params
• Summarize endpoint combines query params (search filters) with POST body (summary config)
• Topics endpoint returns {total, data} not {status, numResults, results} like other endpoints
• showReprints=false is recommended to avoid duplicate AP/Reuters wire-service content
• Company symbols is an array (companies can trade on multiple exchanges)
• Journalist lookup by ID uses /v1/journalists/{id} (not the /all search endpoint)
• Source bias ratings may be null if no rating agency has evaluated the source
• Vector search covers only the last ~6 months of content
• Summarize accepts a prompt to guide focus but has a 2048-character limit