Perigon MCP Server

• 🚀 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.

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

Monitors 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. Durable files live under artifacts/ (exports and query results go there automatically). Put user-facing deliverables in artifacts/output/. File and shell tools can write elsewhere in the workspace, but only artifacts/ is backed by persistent storage.

4. After a sandbox restart, the workspace ID stays valid. The Jupyter kernel and in-memory Python state reset; files under artifacts/ remain. Other workspace paths may be empty on a fresh sandbox.

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.

ChatGPT plugin skills

Workflow instructions for OpenAI’s plugin format live under skills/. Each skill is a folder with a SKILL.md file (YAML name + description, then procedure)—see Skills and Build skills.

Point the plugin manifest at "skills": "./skills/". You can import skills from the deployed MCP server via Scan Tools in the submission portal, or ship this directory in the plugin package.

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. Copy .dev.vars.example to .dev.vars (gitignored) and fill in values.

The dev server binds to local-mcp.perigon.io (see vite.config.ts). Add this line to /etc/hosts so that hostname resolves on your machine:

127.0.0.1 local-mcp.perigon.io

bun i
bun dev
bun test

bun dev serves the MCP worker and the playground at https://local-mcp.perigon.io:5173.

Contributing and maintainers

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

Report security issues privately. See SECURITY.md. Do not open a public issue.

Maintained by the Perigon team.

License

Apache-2.0