Perigon MCP Server

Perigon MCP

Perigon 托管的 MCP 服务，提供实时新闻、实体和监控功能。

• 🚀 快速开始
• 🔐 身份验证
• 🔧 选择工具
• 🛠️ 工具
• 📚 提示词和资源
• 📊 Signal Insights 工作流
• 💡 提示词技巧
• 📦 MCP Registry
• 💻 本地开发
• 👥 贡献与维护者
• ⚖️ 许可证

---

快速开始

端点：https://mcp.perigon.io/v1/mcp

在 Playground 中试用（需要登录 Perigon 控制面板）。面向用户的设置说明：perigon.io/docs/api/mcp。**使用 Agent 安装：**将 perigon.io/mcp.md 提供给 AI 客户端，并按照步骤操作（通过 OAuth 登录，无需在聊天中提供 API 密钥）。

OAuth（推荐）

只需添加服务 URL。首次连接时，客户端会发现 OAuth 元数据并打开 Perigon 登录页面。参见身份验证。

原生 Streamable HTTP：

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

mcp-remote（不支持原生 HTTP 的客户端）：

{
  "mcpServers": {
    "perigon": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://mcp.perigon.io/v1/mcp"]
    }
  }
}

Claude Code：

claude mcp add --transport http perigon https://mcp.perigon.io/v1/mcp

然后在 Claude Code 中运行 /mcp，并在出现提示时选择身份验证。

Codex CLI — 添加到 ~/.codex/config.toml：

[mcp_servers.perigon]
url = "https://mcp.perigon.io/v1/mcp"

然后运行 codex mcp login perigon。

API 密钥（脚本和固定密钥）

当客户端无法完成 OAuth，或需要在配置中固定使用某个密钥时使用。密钥可从 perigon.io/dev/keys 获取。

原生 Streamable HTTP：

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

mcp-remote：

{
  "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"

为兼容旧版客户端，仍提供 /v1/sse 上的 SSE。新集成请使用 Streamable HTTP。

---

身份验证

MCP 端点接受以下两种形式的 Authorization: Bearer 凭据：

方法	Bearer 值	最适用场景
OAuth	Perigon 授权流程颁发的 MCP 访问令牌	桌面和 IDE MCP 客户端；访问权限遵循你所属的组织成员资格
API 密钥	开发者控制面板中的 Perigon API 密钥	脚本、mcp-remote 或固定使用某个密钥的配置

OAuth

托管发现（生产环境）：

• 受保护资源：https://mcp.perigon.io/.well-known/oauth-protected-resource（别名：https://mcp.perigon.io/.well-known/oauth-protected-resource/v1/mcp）
• 授权服务器元数据：https://mcp.perigon.io/.well-known/oauth-authorization-server

客户端从授权服务器元数据中发现授权、令牌和注册端点（必须使用 PKCE）。

客户端完成标准的授权码流程并使用 PKCE，然后在每个 MCP 请求中发送由此获得的访问令牌。

• 登录要求用户是已验证的 Perigon 用户，且在组织中至少具有 User 角色。
• 使用费用计入你的组织。客户端无需 API 密钥。
• 撤销 MCP 访问权限或移除成员会在下一个请求时生效。

未通过身份验证的请求会收到 401 响应，其中包含指向受保护资源元数据 URL 的 WWW-Authenticate 标头。

API 密钥

在 perigon.io/dev/keys 创建或复制密钥，并将其设置在客户端的 Authorization 标头中（请参阅快速入门示例）。范围和配额遵循该密钥的设置。

---

选择工具

在 MCP URL 后附加 ?tools=，以限制会话可用的工具。?tool= 是其别名；如果两者都存在，则优先使用 ?tool=。

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
https://mcp.perigon.io/v1/mcp?tools=all

• 使用逗号分隔的工具名称、配置别名，或两者混用。
• 筛选结果会与凭据允许的范围取交集（API 密钥范围，或 OAuth 的组织 MCP 访问权限），无法扩大访问权限。
• 省略参数或传入空值 → 使用默认集合（选择启用的工具保持关闭；工具列表较小，可节省令牌）。
• 传入 all → 范围允许的默认工具，以及目录中的所有选择启用工具（监控写入、平台辅助工具、get_source_by_id、get_top_topics、get_story_stats 等）。受范围限制的搜索工具仍需要相应权限。
• 未知名称会被忽略。如果所有名称都未知，则使用默认集合。

配置	工具
research	search_news_articles、search_news_stories、search_story_history、search_vector_news、summarize_news、search_journalists、search_sources、search_people、search_companies、search_topics、五个统计工具、get_top_topics、get_source_by_id、get_api_access。不包括 Wikipedia，也不包括公司／人物／地点快捷工具。
monitoring	所有监控工具（包括 create_monitor／update_monitor），以及所有 Signal Insights 工具。
platform	watchlists、create_watchlist、update_watchlist、source_groups、create_source_group、update_source_group、contact_points、article_refresh、get_api_access。
minimal	search_news_articles、五个统计工具、get_api_access。

get_story_stats 不属于任何配置。请按名称请求。需要 CLUSTERS 范围。

---

工具

可用性：

• 默认 — 省略 ?tools= 时注册（如果有要求，密钥还必须具有列出的范围）。
• 范围 — 仅在密钥具有相应权限时注册。
• 选择启用 — 不包含在默认集合中。按名称、配置或使用 ?tools=all 请求。注册不等同于 API 访问权限。

搜索

工具	可用性	描述
search_news_articles	默认	按关键词和筛选条件搜索单篇文章，包括布尔查询。
search_news_stories	范围：CLUSTERS	将相关文章归为同一叙事的聚类标题。
search_story_history	范围：CLUSTERS	带时间戳的快照，展示故事聚类的变化。
search_vector_news	范围：VECTOR_SEARCH_NEWS	对近期文章进行语义搜索。
summarize_news	范围：SEARCH_SUMMARY	对匹配文章进行 AI 摘要，并附上引用。
search_journalists	范围：JOURNALISTS	记者和新闻工作者的个人资料。
search_sources	范围：SOURCES	新闻出版物和媒体机构。
search_people	范围：PEOPLE	公众人物的个人资料。
search_companies	范围：COMPANIES	公司资料（域名、股票代码、行业）。
search_topics	范围：TOPICS	Perigon 主题分类体系，用于精确筛选主题。
search_wikipedia	范围：WIKIPEDIA	按关键词搜索维基百科页面。
search_vector_wikipedia	范围：VECTOR_SEARCH_WIKIPEDIA	对维基百科页面进行语义搜索。

快捷方式

每个工具都会先查找一个实体，然后搜索与其相关的近期文章。

工具	可用性	描述
get_company_news	范围：COMPANIES	按名称查找公司并获取其近期相关文章。
get_person_news	范围：PEOPLE	按名称查找人物并获取其近期相关文章。
get_location_news	范围：LOCATIONS	获取某个城市、州或国家的近期文章。

统计

对任何有效密钥始终可用。相比手动统计搜索结果，请优先使用这些工具。

工具	可用性	描述
get_avg_sentiment	默认	按时间分段统计平均情绪（正面 / 负面 / 中性）。
get_article_counts	默认	按时间分段统计文章发布量。
get_top_entities	默认	被提及次数最多的主题、人物、公司、城市、记者或媒体来源。
get_top_people	默认	报道热度相较基线正在上升的人物。
get_top_companies	默认	报道热度相较基线正在上升的公司。

访问权限

工具	可用性	描述
get_api_access	默认	此密钥的范围、组织、配额和权限行为。调用此工具不会占用请求配额。每个会话调用一次，或在收到 403 后调用。

监控器

读取工具默认启用。写入工具需要选择启用，因为共享监控器架构较大。

工具	可用性	描述
list_monitors	默认	按 UUID、名称、状态或 EVENT / MENTIONS / TOPIC 列出并筛选监控器。
get_monitor	默认	完整的监控器配置。
get_monitor_events	默认	来自 EVENT 和 MENTIONS 监控器的结构化事件。
get_monitor_newsletters	默认	计划简报，通常来自 TOPIC 监控器。
get_monitor_summaries	默认	滚动更新的 AI 生成监控器摘要历史记录。
set_monitor_status	默认	激活、暂停或归档监控器。通过公共 API 无法撤销归档操作。
create_monitor	选择启用	创建 DRAFT 或 ACTIVE 监控器。默认为 DRAFT。
update_monitor	选择启用	部分更新；未提供的字段将保留。

schedulePolicy 中的小时和日期是 timezoneId 时区下的挂钟时间，与 Perigon 产品中的 Delivery 设置一致。公共 API 以 UTC 存储这些时间段；此服务会在读取和写入时进行转换。America/Chicago 时区每天凌晨 3:00 的简报会以 hour: 3 返回并被接受，而不是 hour: 8。get_monitor 还会包含一行易读的 Schedule:。月度计划会保留已配置的 daysOfMonth（包括第 31 天）。间隔超过 24 个的复杂监控器在读取时会回退为有损的每周转换，以确保返回的计划仍可通过 MCP 更新；转换后会超过 24 个间隔的写入会被拒绝，而不会进行近似转换。

平台

以下工具均需选择启用。get_source_by_id 和 get_top_topics 也包含在 research 中。get_story_stats 仅按名称提供。

工具	可用性	描述
get_source_by_id	选择启用	按精确 ID 或域名获取一个新闻来源。
get_top_topics	选择启用	相较于基准线，报道量激增的主题。
get_story_stats	选择启用；范围：CLUSTERS	随时间变化的故事级发布量或发布速度。
watchlists	选择启用	列出、获取或解析组织监控列表。
create_watchlist / update_watchlist	选择启用	创建或部分更新监控列表。
source_groups	选择启用	列出、获取或解析自定义来源组集合。
create_source_group / update_source_group	选择启用	创建或部分更新来源组。
contact_points	选择启用	列出或获取监控器通知渠道（电子邮件 / webhook）。
article_refresh	选择启用	检查刷新任务，或查看最多 100 个文章 ID 的缓存数据。只读。

Signal Insights

除非 ?tools= 将其排除，否则每个会话都会注册这些工具。

monitoring 配置包含这组工具。没有仅包含 Signal Insights 的配置；如果只需要这些工具，请传入工具名称。

工具	可用性	描述
signal_insights_create_workspace	默认	创建工作区。在对话开始时调用一次。
signal_insights_search_signals	默认	按名称或目标搜索信号。
signal_insights_read_signal	默认	信号元数据（分类、架构或简报数量）。
signal_insights_list_newsletters	默认	TOPIC 信号的简报标题和摘录。
signal_insights_read_newsletter	默认	完整的 Markdown 格式简报内容。
signal_insights_export_events	默认	将 EVENT / MENTIONS 事件导出到工作区。返回预览和文件路径。
signal_insights_execute_code	默认	在工作区运行 Python 分析（pandas、numpy、matplotlib）。
signal_insights_preview_chart	默认	在交互式图表查看器中渲染图表。
signal_insights_shell	默认	在工作区运行 shell 命令。
signal_insights_list_files	默认	列出工作区中的文件。
signal_insights_read_file	默认	读取工作区文件。
signal_insights_write_file	默认	写入工作区文件。
signal_insights_grep	默认	在文件内容中进行正则表达式搜索。
signal_insights_str_replace	默认	在文件中查找并替换字符串。

---

提示词和资源

支持 MCP 提示词的宿主可以调用以下工作手册：

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

按需参考资源：

• perigon://reference/fields — 响应字段的语义
• perigon://reference/chaining — 跨端点研究工作手册
• perigon://reference/entitlements — 本会话的范围与行为映射
• perigon://reference/charts — Signal Insights 图表格式规则

MCP Apps 查看器（启用任何 Signal Insights 工具时注册）：

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

---

Monitors Insights 工作流

1. 在对话开始时调用一次 signal_insights_create_workspace。
2. 将返回的工作区 ID 传递给之后的每个分析工具。
3. 持久化文件存放在 artifacts/ 下（导出内容和查询结果会自动保存到此处）。面向用户的交付内容请放在 artifacts/output/ 中。文件和 shell 工具可以写入工作区中的其他位置，但只有 artifacts/ 由持久化存储支持。
4. 沙盒重启后，工作区 ID 仍然有效。Jupyter 内核和内存中的 Python 状态会重置；artifacts/ 下的文件会保留。在全新的沙盒中，工作区的其他路径可能为空。

---

提示词技巧

向模型提供当前日期（或日期工具）。否则，有些模型会将其知识截止日期当作“今天”，并获取过时的新闻。

示例：

• 列出美国今天最重要的 5 条政治头条。
• 查找加利福尼亚本周最新的科技新闻。
• 找出报道可再生能源的记者，然后展示他们近期的文章。
• 搜索 Tesla，然后查找近期与其相关的报道。
• 列出我启用中的事件监控，并显示其中一个监控的最新事件。
• 为半导体行业高管离职创建一个监控草稿。

---

ChatGPT 插件技能

OpenAI 插件格式的工作流说明位于 skills/ 下。每项技能都是一个包含 SKILL.md 文件的文件夹（YAML name + description，后接操作步骤）——请参阅技能和构建技能。

技能	目录	触发条件
新闻研究	skills/news-research/	标题、实体、趋势、记者、引用简报
Monitor Insights	skills/monitor-insights/	监控项、事件、新闻简报、Signal Insights 分析

将插件清单指向 "skills": "./skills/"。你可以通过提交门户中的 Scan Tools 从已部署的 MCP 服务导入技能，也可以将此目录打包到插件中。

---

MCP Registry

Registry 名称：io.github.goperigon/perigon-mcp-server。

server.json 是唯一可信来源。已发布的版本不可更改。任何列表变更后，都要递增 server.json 中的 version 并重新发布。

---

本地开发

此仓库使用 Bun。将 .dev.vars.example 复制为 .dev.vars（已加入 gitignore），然后填写相应值。

变量	必需	说明
ANTHROPIC_API_KEY	是	worker 启动时必须设置；任意非空值均可。只有在游乐场聊天（/v1/api/chat）中才需要真实密钥。
PERIGON_API_KEY	游乐场	使用手动 API 密钥进行测试时，作为游乐场的默认密钥。
PERIGON_API_URL	可选	Perigon API 基础 URL。本地开发时，默认值在 wrangler.jsonc 中设置。
PERIGON_APP_URL	可选	应用基础 URL，用于发现元数据中链接到的 OAuth 授权页面。
MCP_PUBLIC_URL	可选	OAuth 元数据中使用的公共 MCP 来源（默认为本地开发 URL）。

开发服务器绑定到 local-mcp.perigon.io（请参阅 vite.config.ts）。将此行添加到 /etc/hosts，使该主机名能在你的计算机上解析：

127.0.0.1 local-mcp.perigon.io

bun i
bun dev
bun test

bun dev 会在 https://local-mcp.perigon.io:5173 提供 MCP worker 和游乐场。

---

贡献与维护者

如有错误、缺少工具或使用场景，请提交 GitHub issue 或拉取请求。Perigon 团队会进行审核。

请私下报告安全问题。请参阅 SECURITY.md。请勿公开提交 issue。

由 Perigon 团队维护。

---

许可证

Apache-2.0