Perigon MCP

Perigon's hosted MCP server for real-time news, entities, and monitors.

• 🚀 Quick start
• 🔧 Choosing tools
• 🛠️ Tools
• 📚 Prompts and resources
• 📊 Signal Insights workflow
• 💡 Prompting tips
• 📦 MCP Registry
• 💻 Local development
• 👥 Contributing and maintainers
• ⚖️ License

Quick start

Endpoint: https://mcp.perigon.io/v1/mcp

Auth: Authorization: Bearer <key> — create a key at perigon.io/dev/keys.

Try it in the playground (requires a signed-in Perigon dashboard session). Client-specific setup: dev.perigon.io/docs/mcp.

Native Streamable HTTP (recommended):

{
  "mcpServers": {
    "perigon": {
      "url": "https://mcp.perigon.io/v1/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Bearer YOUR_PERIGON_API_KEY"
      }
    }
  }
}

mcp-remote (clients without native HTTP):

{
  "mcpServers": {
    "perigon": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://mcp.perigon.io/v1/mcp",
        "--header",
        "Authorization: Bearer ${PERIGON_API_KEY}"
      ],
      "env": {
        "PERIGON_API_KEY": "YOUR_PERIGON_API_KEY"
      }
    }
  }
}

Claude Code:

claude mcp add --transport http perigon https://mcp.perigon.io/v1/mcp \
  --header "Authorization: Bearer YOUR_PERIGON_API_KEY"

SSE at /v1/sse exists for legacy clients. Use Streamable HTTP for new integrations.

Choosing tools

Append ?tools= to the MCP URL to limit the session. ?tool= is an alias and wins if both are present.

https://mcp.perigon.io/v1/mcp?tools=search_news_articles,search_news_stories
https://mcp.perigon.io/v1/mcp?tools=research
https://mcp.perigon.io/v1/mcp?tools=research,create_monitor

• Comma-separated tool names, profile aliases, or a mix.
• The filter intersects with what the key's scopes already allow. It cannot expand access.
• Omit the parameter, pass an empty value, or pass all → default set (opt-in tools stay off).
• Unknown names are dropped. If every name is unknown, the default set is used.

get_story_stats is not in any profile. Request it by name. It still requires CLUSTERS at call time; a key without that scope can select the tool and then get a permission error.

Other opt-in tools need no extra scope. Any valid key can request them.

Tools

Availability:

• Default — registered when ?tools= is omitted (and the key has the listed scope, if any).
• Scope — registered only when the key has that permission.
• Opt-in — omitted from the default set. Request by name or profile. Registration is not the same as API access.

Search

Shortcuts

Each tool looks up an entity, then searches recent articles about it.

Stats

Always on for any valid key. Prefer these over counting search results by hand.

Access

Monitors

Read tools are default. Write tools are opt-in because the shared monitor schema is large.

Platform

All of these are opt-in. get_source_by_id and get_top_topics are also in research. get_story_stats is name-only.

Signal Insights

Registered for every session unless ?tools= excludes them. The Insights API and Pokey backend reject calls when the key lacks Signal Insights access.

The monitoring profile includes this set. There is no Signal Insights-only profile; pass the tool names if you want only these.

Prompts and resources

Hosts that support MCP prompts can invoke these playbooks:

• entity_deep_dive
• narrative_trace
• coverage_trend
• journalist_beat_profile
• competitive_landscape
• spike_explainer

On-demand reference resources:

• perigon://reference/fields — response field semantics
• perigon://reference/chaining — cross-endpoint research playbooks
• perigon://reference/entitlements — this session's scope-to-behavior map
• perigon://reference/charts — Signal Insights chart formatting rules

MCP Apps viewers (registered when any Signal Insights tool is active):

• ui://signal-insights/chart-viewer
• ui://signal-insights/export-viewer

Signal Insights workflow

1. Call signal_insights_create_workspace once at the start of a conversation.
2. Pass the returned workspace ID to every later analysis tool.
3. Files from signal_insights_execute_code and signal_insights_shell persist in that workspace. Exports land at /home/user/workspace/artifacts/ inside the sandbox.
4. After a restart, the prior workspace UUID is still valid. The kernel is fresh; exported S3 artifacts remain.

Prompting tips

Give the model the current date (or a date tool). Some models otherwise treat their knowledge cutoff as "today" and fetch stale news.

Examples:

• Top 5 political headlines in the United States from today.
• Latest tech news from California this week.
• Find journalists covering renewable energy, then show their recent articles.
• Search for Tesla, then find recent stories about them.
• List my active event monitors and show the latest events from one of them.
• Create a draft monitor for executive departures in semiconductors.

MCP Registry

Registry name: io.github.goperigon/perigon-mcp-server.

server.json is the source of truth. A published version is immutable. Bump version in server.json and republish after any listing change.

Local development

This repo uses Bun. Put secrets in .dev.vars.

To use Perigon dashboard cookies with the playground, add this to /etc/hosts:

127.0.0.1 local-mcp.perigon.io

bun i
bun dev
bun test

bun dev serves the MCP worker and the playground.

Contributing and maintainers

Open a GitHub issue or pull request for bugs, missing tools, or use cases. Someone at Perigon will review it.

Maintained by the Perigon team:

• Lead developer: Vasyl Teliman (feature development, security, server)
• Lead designer: Galen Rutledge (feature development, continued maintenance)
• Initial development: Islem Maboud (transport, auth, deploy, playground)

License

Apache-2.0