Introducing a new way to review your PRs.

Read the announcement

koala73 / worldmonitor

Real-time global intelligence dashboard. AI-powered news aggregation, geopolitical monitoring, and infrastructure tracking in a unified situational awareness interface

View on GitHub

29 documents · Updated Nov 20, 2026

docs / ai-agent-plugin-integration

AI agent plugin integration

WorldMonitor exposes its global-intelligence data to AI-agent environments through MCP connections and task-focused skills. Claude receives a packaged plugin, while Gemini-compatible hosts use extension and plugin manifests; both connect to the hosted WorldMonitor MCP service rather than running local code.

This page belongs to desktop and external clients. Related surfaces include the Tauri desktop application, browser plugin country intelligence, CLI terminal dashboard, SDK client libraries, and Zapier automation integration. It also relates to the domain API routes.

Agent connection model

Hosted MCP service

The hosted MCP service is the shared data boundary for AI agents. It lets a client discover WorldMonitor tools and task guides, then request current intelligence through one remote Streamable HTTP endpoint.

The main connection is https://worldmonitor.app/mcp. The service exposes source-backed monitoring across news, country risk, conflict, markets, energy, trade, shipping, cyber, hazards, and related domains. Access and freshness information remain part of the service response, so an agent can distinguish current data from limited or stale data.

The connection model is intentionally remote:

  • The agent host sends MCP requests over HTTPS.
  • WorldMonitor handles identity, entitlement, allowance, tool selection, and data retrieval.
  • The plugin package does not start a local server or include a data copy.

This diagram shows how an agent moves from a packaged integration to WorldMonitor intelligence.

flowchart LR
    Host[AI-agent host] --> Manifest[Plugin or extension manifest]
    Manifest --> Config[MCP connection config]
    Config --> MCP[WorldMonitor MCP service]
    MCP --> Tools[Tools and task skills]
    Tools --> Answer[Source-backed agent answer]

References: server.json• L2-17 claude-plugin/.mcp.json• L1-8 gemini-extension.json• L1-12

Access and trust boundary

The first protected MCP use can send the agent through WorldMonitor OAuth. A free account can use a small set of cached data within an allowance, while subscription features such as generated briefs and some risk views remain gated. The agent must preserve the service's source dates, freshness state, missing data, and access limits in its answer.

Claude's packaged plugin contains no local hooks, executables, environment credentials, or account-writing actions. It only describes the remote connector and the skills that guide tool use. This keeps the host as the place where the user approves access while WorldMonitor remains the place that enforces it.

References: claude-plugin/README.md• L20-35 claude-plugin/…/plugin.json• L1-17

Plugin manifests

Claude plugin

The Claude package groups product metadata, one MCP connector, documentation, an icon, and a curated set of skills into a directory that Claude can install. Its connector points only to the canonical WorldMonitor MCP endpoint, so adding the plugin and adding the connector separately resolve to the same tool service.

The packaged Claude skills focus on common intelligence tasks:

SkillPrimary use
world-briefGlobal developments and headlines
country-briefingA country risk briefing
conflict-pulseRecent fighting and conflict activity
chokepoint-checkMaritime chokepoint disruption
hazard-watchRecent natural hazards
market-snapshotCurrent market movement
prepare-travel-risk-assessmentA sourced draft assessment for a multi-country trip

Each skill tells Claude which live MCP tools to use and how to keep dates, sources, access gaps, and data limits visible. The package is therefore a guided entry point into the broader MCP catalog, not a separate intelligence product.

References: claude-plugin/…/plugin.json• L1-27 claude-plugin/.mcp.json• L1-8 claude-plugin/README.md• L5-22 tests/claude-plugin-package.test.mjs• L52-121

Gemini extension

The Gemini extension configuration gives a Gemini-compatible host two named MCP connections. worldmonitor provides live intelligence, while worldmonitor-docs provides the MCP documentation service at https://www.worldmonitor.app/docs/mcp.

The Antigravity plugin manifest adds the product identity and suggested prompts that help a user start useful requests. Its prompts cover headlines, country risk, and maritime disruption. The manifest is a discovery layer; the MCP connection configuration remains the source of the actual data path.

References: gemini-extension.json• L1-12 .antigravity-plugin/plugin.json• L1-22

Packaged skills

Skill catalog

The public Agent Skills catalog publishes reusable SKILL.md guides for agents that need a focused recipe instead of a full tool inventory. Each guide explains when to use the skill, the expected access shape, the relevant request path, response meaning, and how to treat upstream text as data rather than instructions.

The catalog covers the main WorldMonitor intelligence lanes:

  • Country and strategic risk
  • Conflict, instability, and security
  • Markets, trade, and forecasts
  • Maritime, logistics, and energy
  • Live monitoring and hazards

The prepare-travel-risk-assessment skill adds a focused workflow for a sourced first draft across up to six countries. It leaves uncovered topics for analyst completion and tells the agent to distinguish reported findings from empty, unavailable, and uncovered source areas.

The machine-readable discovery index is https://worldmonitor.app/.well-known/agent-skills/index.json. Its entries point to served skill files and include SHA-256 digests so an agent can verify the exact recipe it received.

References: docs/agent-skills.mdx• L6-25 docs/agent-skills.mdx• L27-81 public/…/index.json• L1-10 public/…/SKILL.md• L1-18

MCP skill resources

The MCP service also exposes the skill catalog through the Skills extension. An MCP client can list the available skills, get one skill by its skill:// URI, and read its digest-bound resource. The list response is limited to the first five entries and does not provide continuation cursors, while skills/get and resources/read keep the full recipe collection accessible.

Skill files are generated from the public catalog and served as text resources. The resource contract includes a URI, MIME type, byte size, and digest. These fields let clients detect a stale or altered skill before relying on its instructions.

References: api/…/index.ts• L12-65 tests/mcp-skills-extension.test.mts• L20-100 api/…/generated.ts• L1-17

Distribution contracts

Skill build and synchronization

The public skill files are the source for several agent-facing forms. The skill build process creates the discovery index, creates the generated MCP skill resources, and materializes regular files for the root Agent Plugins layout. It also removes stale generated skills and rewrites API examples to the public documentation host when needed.

This synchronization makes one skill definition serve several consumers:

ConsumerPublished form
Agent Skills discoverypublic/…/index.json and served SKILL.md files
MCP clientsGenerated skill://... resources
Agent PluginsRoot skills/…/SKILL.md files
Claude directory pluginCurated files under claude-plugin/skills/

The build check compares these forms. A changed skill is not complete until its public bytes, digest, generated MCP resource, and packaged plugin copy agree.

References: scripts/build-agent-skills-index.mjs• L121-145 scripts/build-agent-skills-index.mjs• L226-266 scripts/build-agent-skills-index.mjs• L279-356 package.json• L130-138

MCP registry publication

The MCP server card is a separate distribution contract for clients that discover servers through the official MCP registry. It names WorldMonitor, declares the streamable-http remote, and points clients to the same canonical endpoint used by the plugins.

Automated publication follows changes to registry inputs and a daily backstop. Release and manual runs remain available. The workflow validates the prepared manifest, authenticates the publisher, and retries publication without creating a second version when the first attempt already succeeded.

Publication is versioned and fail-closed. If the registry already has the same version, publication succeeds only when the stored manifest is equivalent and active. A payload difference or inactive record blocks reuse of that version instead of silently exposing a mismatched server description.

References: server.json• L2-17 .github/…/publish-mcp-registry.yml• L1-18 .github/…/publish-mcp-registry.yml• L73-103 scripts/publish-mcp-registry.mjs• L173-202 scripts/publish-mcp-registry.mjs• L229-308 tests/publish-mcp-registry.test.mjs• L126-151

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the Claude connector URL and Gemini connection URLs aligned with the canonical MCP endpoint and the published server card.
  • When a skill changes, rebuild the discovery index, generated MCP resources, root plugin files, and any curated Claude copy that uses it.
  • Keep skill names, front-matter descriptions, MCP tool tables, access classes, REST examples, and digest values in sync.
  • When MCP skill discovery changes, preserve the bounded first-page contract and keep the full skill content reachable through direct lookup and resource reads.
  • Treat plugin package versions, extension versions, and MCP registry server versions as separate contracts. Update the contract that changed.
  • When changing MCP access or freshness behavior, update the agent guidance that tells users what a free, gated, stale, or missing result means.

Important failure modes

TriggerConsequenceGuard
A plugin points to a non-canonical MCP URLThe host can see a different service or follow an unexpected redirectKeep plugin configs and server.json on https://worldmonitor.app/mcp
A skill changes but its generated copies are not rebuiltAgents receive stale tool names, request shapes, or digestsRun the agent-skill build check before distribution
A client sends a continuation cursor to skills/listThe client receives an invalid-parameter error instead of a catalog pageOmit cursors and use skills/get or resources/read for the full collection
A skill omits access or freshness limitsAn agent can present gated, stale, or partial data as completeKeep auth, source dates, data gaps, and content-safety guidance in each recipe
An existing registry version has a different manifestA version label can point to a changed server contractFail closed and publish a new version
A package adds a credential, executable, or local hookInstallation can cross the intended remote-only trust boundaryKeep the Claude bundle limited to its manifest, connector, docs, icon, and skill files

Key files

FileWhy to read it
claude-plugin/README.mdExplains the Claude connector, curated skills, access model, and remote-only limits.
claude-plugin/…/plugin.jsonDefines Claude package identity, support links, and distribution metadata.
claude-plugin/.mcp.jsonDefines the Claude MCP connection.
gemini-extension.jsonDefines the Gemini-compatible MCP connections.
.antigravity-plugin/plugin.jsonDefines Gemini/Antigravity product metadata and suggested prompts.
scripts/build-agent-skills-index.mjsShows how public skills become discovery, MCP, and Agent Plugin artifacts.
public/…/index.jsonShows the public skill discovery contract and digest model.
public/…/SKILL.mdDescribes the packaged travel-risk workflow and its agent-facing data rules.
api/…/index.tsShows the MCP-facing skill list, lookup, and resource contract.
server.jsonDefines the published MCP server card and canonical remote.
.github/…/publish-mcp-registry.ymlDefines when and how the MCP server card reaches the registry.
scripts/publish-mcp-registry.mjsShows the version and manifest safety rules for registry publication.