Perigon

Perigon MCP

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

• 🚀 Quick start
• 🔐 Authentication
• 🔧 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

Try it in the playground (requires a signed-in Perigon dashboard session). Human-oriented setup: perigon.io/docs/api/mcp. Install with an agent: pass perigon.io/mcp.md to your AI client and follow the steps (OAuth sign-in, no API key in chat).

OAuth (recommended)

Add the server URL only. On first connect, the client discovers OAuth metadata and opens Perigon sign-in. See Authentication.

Native Streamable HTTP:

{

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

`mcp-remote` (clients without native 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

Then run /mcp in Claude Code and choose Authenticate when prompted.

Codex CLI — add to ~/.codex/config.toml:

[mcp_servers.perigon]

url = "https://mcp.perigon.io/v1/mcp"

Then run codex mcp login perigon.

API key (scripts and pinned keys)

Use when the client cannot complete OAuth or you need a fixed key in config. Keys from perigon.io/dev/keys.

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

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

---

Authentication

The MCP endpoint accepts `Authorization: Bearer` credentials in two forms:

OAuth

Hosted discovery (production):

• Protected resource: https://mcp.perigon.io/.well-known/oauth-protected-resource (alias: https://mcp.perigon.io/.well-known/oauth-protected-resource/v1/mcp)
• Authorization server metadata: https://mcp.perigon.io/.well-known/oauth-authorization-server

Clients discover the authorization, token, and registration endpoints from the authorization server metadata (PKCE required).

The client completes the standard authorization-code flow with PKCE, then sends the resulting access token on every MCP request.

• Sign-in requires a verified Perigon user with at least User role in the organization.
• Usage is billed to your organization. No API key is needed in the client.
• Revoking MCP access or removing a member takes effect on the next request.

Unauthenticated requests receive 401 with a WWW-Authenticate header pointing at the protected-resource metadata URL.

API key

Create or copy a key at perigon.io/dev/keys and set it in the client’s Authorization header (see Quick start examples). Scopes and quotas follow that key.

---

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

• Comma-separated tool names, profile aliases, or a mix.
• The filter intersects with what your credentials allow (API key scopes or your org’s MCP access for OAuth). It cannot expand access.
• Omit the parameter or pass an empty value → default set (opt-in tools stay off; smaller tool list for token savings).
• Pass all → scope-allowed default tools plus every opt-in catalogue tool (monitor write, platform helpers, get_source_by_id, get_top_topics, get_story_stats, and the rest). Scope-gated search tools still require the matching permission.
• 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. Requires the CLUSTERS scope.

---

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, profile, or ?tools=all. 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.

schedulePolicy hours and days are wall-clock times in timezoneId, matching Delivery settings in the Perigon product. The public API stores those intervals in UTC; this server converts on read and write. A daily 3:00 AM America/Chicago briefing is returned and ac