Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ichi-mcp what's the current internet cyber health index?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A minimal Model Context Protocol (MCP) stdio
server, built on the official Python mcp SDK, that lets an AI assistant read
the free public ICHI API. No API key is needed.
ICHI — the Internet Cyber Health Index — is a free, publicly accessible, source-transparent daily barometer of internet-wide cyber threat conditions, created by Joe Bernik. It is an outside-in directional signal. It is not an organization-specific risk score, not a deterministic forecast, and not a substitute for your own internal telemetry. The band is the operative read; moves within a band should be treated as noise. See the methodology.
This repository is maintained by/for ICHI's creator.
Related MCP server: winfolio
Tool | Source | Returns |
|
| score, rounded score, band + band range, evaluation time, model, per-dimension sub-scores with human-readable names and contributions, informational (unscored) values, freshness/impairment info (headline state, age, stale/impaired/invalid inputs, degraded dimensions), links |
|
| latest N (1–50) items from ICHI's critical-advisory feed: title, link, id, published (ISO-8601), category, description |
|
| overall status and confidence, feed counts (live/stale/delayed/failed, by tier), sources included in the score, and names of failed/stale/delayed/dormant/not-connected feeds |
Every tool returns a JSON object with "ok": true, or "ok": false plus an
"error" message on timeouts, HTTP errors, or unparseable responses — the
server never crashes on a bad upstream response.
Requires Python ≥ 3.10. With uv:
uvx --from git+https://github.com/bernik-bot/ichi-mcp ichi-mcpPin a release with git+https://github.com/bernik-bot/ichi-mcp@v0.1.0.
Or with pip: pip install git+https://github.com/bernik-bot/ichi-mcp then run ichi-mcp.
(Not published on PyPI.)
Add to claude_desktop_config.json
(macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"ichi": {
"command": "uvx",
"args": ["--from", "git+https://github.com/bernik-bot/ichi-mcp", "ichi-mcp"]
}
}
}If uvx isn't on Claude Desktop's PATH, use its absolute path (which uvx).
{
"command": "uvx",
"args": ["--from", "git+https://github.com/bernik-bot/ichi-mcp", "ichi-mcp"],
"env": { "ICHI_TIMEOUT": "10" }
}Env var | Default | Meaning |
|
| HTTP timeout in seconds |
|
| API base URL (testing only) |
{
"ok": true,
"score": 64.91,
"rounded": 65,
"band": "ELEVATED",
"band_range": "50-69",
"evaluated_at": "2026-10-31T13:30:22.978Z",
"model": "v7.1",
"dimensions": [
{"key": "V", "name": "Vulnerability Pressure", "score": 42.21, "contribution": 8},
{"key": "C", "name": "C2 / Malware Infrastructure", "score": 96.03, "contribution": 13.14}
],
"freshness": {"headline_state": "LIVE", "age_seconds": 267, "completeness": "COMPLETE", "stale_inputs": [], "impaired_sources": []},
"link": "https://ichi.global"
}Reads only ICHI's public endpoints; it does no scoring of its own and adds no data.
Dimension names are mapped from API keys using the published methodology
(model v7.x). The API key P is the phishing-driven dimension the methodology
labels "O — Actor Operations"; the informational O value is labelled as
Outages. Unknown keys are passed through unchanged. If ICHI's schema changes,
missing fields come back as null rather than errors.
The alerts feed is ICHI's critical-advisory RSS feed; per its own description it is observation only and carries no score.
No caching: each tool call makes one HTTP request. ICHI's current index is re-evaluated about every 10 minutes.
uv venv && uv pip install -e ".[dev]"
ruff check . && pytest -q # tests mock HTTP, no network
python examples/smoke_client.py # live end-to-end over stdio via the MCP clientWorks with both mcp 1.x (FastMCP) and 2.x (MCPServer, the renamed FastMCP);
CI tests both.
MIT
Get the current ICHI score (0-100), band (NORMAL/GUARDED/ELEVATED/HIGH/CRITICAL), per-dimension sub-scores with human-readable names, and freshness/impairment info.
ICHI is an outside-in, internet-wide directional signal - not an organization-specific risk score or a forecast.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, and it does most of the work: it discloses the exact output shape, the band enumeration, freshness/impairment inclusion, and critically the interpretation limits ('not an organization-specific risk score or a forecast'). It never states read-only status, auth needs, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Output contents are front-loaded in the first sentence and the interpretive caveat follows as a compact second paragraph. Both sentences earn their place, though the block formatting of the caveat is slightly longer than a single clause would need to be.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so the description needn't document return values, and it nonetheless enumerates them briefly. Combined with the semantic caveat about what the index is not, this is nearly complete for a zero-parameter read tool; only operational traits like caching/freshness cadence are absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline is 4. There is no parameter semantics to add and the description correctly does not waste space on inputs; 'current' implies no time arguments are accepted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource ('Get the current ICHI score') and enumerates the returned content: score (0-100), band with named levels, per-dimension sub-scores, and freshness/impairment info. That is far more precise than a tautology, but it never names get_recent_alerts or get_source_health, so sibling differentiation is left implicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: 'current' suggests a point-in-time snapshot versus the recency/health framing of the siblings, and the caveat that this is 'outside-in, internet-wide' hints at when the signal is and isn't appropriate. There is no explicit when-to-use, when-not, or alternative-naming guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the latest items (default 5, max 50) from ICHI's critical-advisory RSS feed (https://ichi.global/api/alerts): title, link, published time, category, description.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses that results come from a remote third-party RSS endpoint and that limits are bounded (default 5, max 50), which hints at latency/cost, but says nothing about freshness, caching, or how feed fetch failures are surfaced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One front-loaded sentence with the resource and default/max limits stated before the return fields. The embedded URL is arguably extra weight but earns its place as provenance for the data source.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-optional-parameter read tool with an output schema present, the definition covers source, size bounds, and key returned fields, which is enough to call it correctly. Only failure/refresh behavior is left unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the single 'limit' parameter has only a default. The description supplies the missing upper bound (max 50), which is real information the schema does not convey, though it doesn't say what 'limit' counts or what happens if values exceed 50.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (retrieve latest items from ICHI's critical-advisory RSS feed) and even names the backing endpoint, plus enumerates the returned fields. An agent can tell this is an external advisory-feed reader, distinct from get_current_index and get_source_health, though the description never says so explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to call this versus the sibling tools, no prerequisites, no exclusions. The only usage signal is implicit in the 'default 5, max 50' limits, which says how much to fetch, not when to fetch it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Summarize ICHI's source health (https://ichi.global/api/health): overall status, confidence, live/stale/failed feed counts, and which sources feed the score.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden, and it does confirm this is a read-only summary by describing the information returned rather than any mutation. It gives no behavioral context such as freshness semantics, upstream dependency on the referenced health endpoint, or failure modes if that endpoint is unreachable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence that enumerates the key returned fields with no filler. Every clause earns its place by telling the agent what it will get.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read tool with a full output schema covering return values, the description supplies enough context to call it correctly. The only gap is the absence of explicit routing guidance relative to get_current_index and get_recent_alerts.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline of 4 applies; there is no parameter meaning for the description to add. The schema and description are consistent on this point.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Summarize') and resource ('ICHI's source health') and enumerates the returned dimensions: overall status, confidence, feed counts, and contributing sources. This is clearly distinct from get_current_index and get_recent_alerts by content, though the description never names those siblings to make the distinction explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the name and the enumerated outputs (health diagnostics versus index value or alerts), but there is no statement of when to prefer this tool over its siblings or any preconditions. An agent must infer the routing from the resource name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_current_indexget_recent_alertsget_source_healthScored across 3 tools
Each tool maps to a clearly separable concern: the current index/score, the advisory alert feed, and source health diagnostics. An agent can decide between them unambiguously from the names alone, and the descriptions reinforce the boundaries (score vs. alerts vs. upstream feeds).
All three tools follow the same get_<noun> pattern (get_current_index, get_recent_alerts, get_source_health), with snake_case throughout and noun phrases that read naturally together.
Three tools is thin but proportionate for a read-only wrapper over a small public API surface; each tool corresponds to a distinct endpoint and none feels redundant. It could arguably use one more tool (e.g. history), but the scope is tight rather than padded.
The read path for the live signal is well covered (value, alerts, feed health), but there is no way to retrieve historical scores or trends, which is a notable gap for something described as a 'directional signal'. Alert retrieval also lacks filtering by category or time beyond a simple count, leaving some agent workflows to work around the surface.
Network, domain and website diagnostics for AI clients via MCP.
Hosted MCP server for live public-data APIs and Skills for AI agents.
See which AI models fall for traps in everyday jobs, and check or scan any MCP server, skill or package before your agent installs it. No sign-in; read-only; returns structured data.
AI Reasoning Cache & Consensus Layer with 11 MCP tools via Streamable HTTP.