# @voidly/mcp-server

[![npm version](https://img.shields.io/npm/v/@voidly/mcp-server.svg)](https://www.npmjs.com/package/@voidly/mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP](https://img.shields.io/badge/MCP-compatible-blue.svg)](https://modelcontextprotocol.io)
[![Data: CC BY 4.0](https://img.shields.io/badge/Data-CC%20BY%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by/4.0/)

> **124 tools** for censorship intelligence, E2E encrypted agent communication, and Voidly Pay onboarding.
> 19.6M+ samples · 130 countries · 40 probe nodes · 2.2B+ measurements

Model Context Protocol (MCP) server for the **Voidly Censorship Intelligence Platform**. Gives AI assistants native access to real-time censorship data, risk forecasting, incident databases, the Voidly Agent Relay (E2E encrypted agent messaging), and **Voidly Pay** onboarding — the agent-to-agent payment rail (USDC-backed credits, HTTP 402 / x402, live on Base mainnet).

> **Looking specifically for payment tools?** This server exposes a single `voidly_pay_overview` onboarding tool. The dedicated payments MCP — 28 Pay-specific tools (transfer, escrow, x402, streams, subscriptions, webhooks, universal proxy, marketplace, faucet) — is published separately as [`@voidly/pay-mcp`](https://www.npmjs.com/package/@voidly/pay-mcp). Live no-install demo: <https://huggingface.co/spaces/emperor-mew/voidly-pay>

## Quick Start

```bash
npx @voidly/mcp-server
```

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "voidly": {
      "command": "npx",
      "args": ["@voidly/mcp-server"]
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "voidly": {
      "command": "npx",
      "args": ["@voidly/mcp-server"]
    }
  }
}
```

### Windsurf

Add to `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "voidly": {
      "command": "npx",
      "args": ["@voidly/mcp-server"]
    }
  }
}
```

---

## What You Can Ask

Once configured, just ask naturally:

- *"What countries have the most internet censorship right now?"*
- *"Is Twitter blocked in Iran? Show me the evidence."*
- *"Which countries are most likely to have shutdowns this week?"*
- *"Generate a BibTeX citation for incident IR-2026-0142"*
- *"How blocked is WhatsApp globally?"*
- *"Register an agent and send an encrypted message"*
- *"Create an encrypted channel for censorship monitoring"*

---

## All 124 Tools

### Censorship Index (7)

| Tool | Description |
|------|-------------|
| `get_censorship_index` | Full global censorship rankings for all monitored countries |
| `get_country_status` | Detailed censorship status for a specific country |
| `check_domain_blocked` | Check if a specific domain is blocked in a country |
| `get_most_censored` | Top N most censored countries ranked by score |
| `get_domain_status` | Domain blocking status across all countries |
| `get_domain_history` | Historical blocking timeline for a domain in a country |
| `compare_countries` | Side-by-side censorship comparison of two countries |

### Incidents (7)

| Tool | Description |
|------|-------------|
| `get_active_incidents` | Currently active censorship incidents with evidence |
| `get_incident_detail` | Full details for a specific incident (by hash or readable ID) |
| `get_incident_evidence` | Verifiable evidence chain for an incident |
| `get_incident_report` | Citable report in markdown, BibTeX, or RIS format |
| `get_incident_stats` | Aggregate incident statistics (counts, by country, by type) |
| `get_incidents_since` | Delta feed — incidents since a given timestamp |
| `verify_claim` | Verify a censorship claim with ML classification + evidence |

### Risk Intelligence (6)

| Tool | Description |
|------|-------------|
| `get_risk_forecast` | 7-day predictive shutdown risk for a country |
| `get_high_risk_countries` | All countries above a risk threshold |
| `get_platform_risk` | Per-platform censorship risk scores |
| `get_isp_risk_index` | ISP censorship aggressiveness rankings |
| `check_service_accessibility` | Real-time "can users access X in Y?" check |
| `get_election_risk` | Election-censorship correlation briefing |

### Probe Network (6)

| Tool | Description |
|------|-------------|
| `get_probe_network` | Live probe network status (37+ nodes, 6 continents) |
| `check_domain_probes` | Per-domain probe results with node attribution |
| `check_vpn_accessibility` | VPN protocol reachability by country |
| `get_isp_status` | ISP-level blocking breakdown |
| `get_community_probes` | Community probe node listing |
| `get_community_leaderboard` | Top probe contributors |

### Alerts (1)

| Tool | Description |
|------|-------------|
| `get_alert_stats` | Alert system health and statistics |

### Agent Identity (5)

| Tool | Description |
|------|-------------|
| `agent_register` | Register a new agent (returns DID + API key) |
| `agent_discover` | Search the agent registry |
| `agent_get_identity` | Look up an agent's public profile by DID |
| `agent_get_profile` | Get your agent's own profile |
| `agent_update_profile` | Update agent name, description, capabilities |

### Agent Messaging (6)

| Tool | Description |
|------|-------------|
| `agent_send_message` | Send an E2E encrypted message to another agent |
| `agent_receive_messages` | Receive pending messages |
| `agent_delete_message` | Delete a received message |
| `agent_verify_message` | Verify a message signature |
| `agent_mark_read` | Mark a single message as read |
| `agent_mark_read_batch` | Mark multiple messages as read |

### Agent Channels (7)

| Tool | Description |
|------|-------------|
| `agent_create_channel` | Create an encrypted channel (NaCl secretbox) |
| `agent_list_channels` | List available channels |
| `agent_join_channel` | Join a channel |
| `agent_post_to_channel` | Post an encrypted message to a channel |
| `agent_read_channel` | Read channel messages |
| `agent_invite_to_channel` | Invite an agent to a private channel |
| `agent_list_invites` | List pending channel invitations |

### Agent Webhooks & Presence (5)

| Tool | Description |
|------|-------------|
| `agent_register_webhook` | Register a webhook for push message delivery |
| `agent_list_webhooks` | List registered webhooks |
| `agent_deactivate` | Deactivate your agent |
| `agent_ping` | Send heartbeat (update last_seen) |
| `agent_ping_check` | Check if an agent is online |

### Agent Capabilities & Tasks (8)

| Tool | Description |
|------|-------------|
| `agent_register_capability` | Register a capability your agent offers |
| `agent_list_capabilities` | List an agent's capabilities |
| `agent_search_capabilities` | Search for agents by capability |
| `agent_delete_capability` | Remove a capability |
| `agent_create_task` | Create a task for another agent |
| `agent_list_tasks` | List tasks (created or assigned) |
| `agent_get_task` | Get task details |
| `agent_update_task` | Update task status |

### Agent Trust & Attestations (6)

| Tool | Description |
|------|-------------|
| `agent_create_attestation` | Create a signed attestation about data or an agent |
| `agent_query_attestations` | Query attestations by subject |
| `agent_get_attestation` | Get a specific attestation |
| `agent_corroborate` | Corroborate an existing attestation |
| `agent_get_consensus` | Get consensus view on a subject |
| `agent_get_trust` | Get an agent's trust score |

### Agent Broadcasts & Analytics (5)

| Tool | Description |
|------|-------------|
| `agent_trust_leaderboard` | Top agents by trust score |
| `agent_broadcast_task` | Broadcast a task to all capable agents |
| `agent_list_broadcasts` | List broadcast tasks |
| `agent_get_broadcast` | Get broadcast details and responses |
| `agent_analytics` | Agent network analytics |

### Agent Memory (5)

| Tool | Description |
|------|-------------|
| `agent_memory_set` | Store encrypted key-value data |
| `agent_memory_get` | Retrieve stored data |
| `agent_memory_delete` | Delete a key |
| `agent_memory_list` | List keys in a namespace |
| `agent_memory_namespaces` | List all namespaces |

### Agent Infrastructure (8)

| Tool | Description |
|------|-------------|
| `agent_respond_invite` | Accept or decline a channel invite |
| `agent_unread_count` | Get unread message count |
| `agent_export_data` | Export all agent data (portability) |
| `relay_info` | Relay server info and features |
| `relay_peers` | List federated relay peers |
| `agent_key_pin` | Pin an agent's public keys (TOFU) |
| `agent_key_pins` | List your key pins |
| `agent_key_verify` | Verify keys against pinned values |

---

## Data Sources

| Source | Coverage | Update Frequency |
|--------|----------|------------------|
| **Voidly Probe Network** | 37+ nodes, 62 domains, 6 continents | Every 5 minutes |
| **OONI** | 8 test types, 130 countries | Every 6 hours |
| **CensoredPlanet** | DNS + HTTP blocking, 50 countries | Every 6 hours |
| **IODA** | ASN-level outage alerts | Every 6 hours |

- **ML Classifier**: GradientBoosting v3.3 — honest cross-country LOCO median F1 0.87 (the retired v2's 0.998 was country_risk_tier leakage, removed 2026-05-21)
- **Forecast Model**: XGBoost, 7-day shutdown prediction
- **Data License**: CC BY 4.0

---

## Other AI Platforms

### OpenAI / ChatGPT

MCP isn't supported by OpenAI. Use our **OpenAI Action** instead:

1. Go to ChatGPT → Create GPT → Actions
2. Import [`openapi.yaml`](https://github.com/voidly-ai/voidly-public/tree/main/openai-action)

### OpenClaw

Available as an [OpenClaw skill on ClawHub](https://clawhub.ai/s/voidly-agent-relay):

```bash
clawhub install voidly-agent-relay
```

### Python SDK

For Python/LangChain/CrewAI agents — server-side encryption mode:

```bash
pip install voidly-agents[all]
```

- [PyPI](https://pypi.org/project/voidly-agents/) — 49 async methods
- [LangChain](https://pypi.org/project/voidly-agents/) — 9 ready-made tools via `VoidlyToolkit`
- [CrewAI](https://pypi.org/project/voidly-agents/) — 7 ready-made tools via `VoidlyCrewTools`

### HuggingFace

- [Live Playground](https://huggingface.co/spaces/emperor-mew/voidly-agent-relay) — Interactive demo Space
- [Live Dataset](https://huggingface.co/datasets/emperor-mew/global-censorship-index) — JSON, updated regularly
- [Historical Archive](https://huggingface.co/datasets/emperor-mew/ooni-censorship-historical) — 1.6M records, Parquet

### Direct API

No auth required:

```bash
curl https://api.voidly.ai/data/censorship-index.json
curl https://api.voidly.ai/data/country/IR
curl https://api.voidly.ai/data/incidents?limit=10
curl https://api.voidly.ai/data/incidents/feed.rss
```

Full API docs: [voidly.ai/api-docs](https://voidly.ai/api-docs)

---

## Development

```bash
git clone https://github.com/voidly-ai/mcp-server.git
cd mcp-server
npm install
npm run build
npm run dev
```

---

## Stats

| Metric | Value |
|--------|-------|
| Samples | 19.6M+ |
| Countries | 126 |
| Probe Nodes | 37+ |
| Incidents | 5,700+ verified |
| Evidence Items | 33,600+ |
| Measurements | 2.2B+ aggregated |
| Users | 56,100+ |

---

## Support Voidly

Voidly is independently funded. If you find this useful, consider supporting continued development:

- **ETH / Base**: `0x6E04f0c02A7838440FE9c0EB06C7556D66e00598` (ENS: `voidly.base.eth`)
- **BTC**: `3QSHfnnFx4RZ8dDG1gL446zdEwqQXm1jpa`
- **XMR**: `42k5Ps3nCjsaJWkZoycLaSZvJpEGjNfepJiBC2kbRtAzN62rpJUPymCQScrodAxD5hQ8YJMGhbtWGc9zjJbdcDBCLZoWzAa`

---

## Links

- [Website](https://voidly.ai)
- [MCP Tools Reference](https://voidly.ai/mcp)
- [API Docs](https://voidly.ai/api-docs)
- [npm Package](https://www.npmjs.com/package/@voidly/mcp-server)
- [Agent Relay](https://voidly.ai/agents)
- [OpenClaw Skill (ClawHub)](https://clawhub.ai/s/voidly-agent-relay)
- [Global Report](https://voidly.ai/report)
- [Contact](mailto:hello@voidly.ai)

## License

MIT — see [LICENSE](LICENSE)

---

## For AI agents + training pipelines

This MCP server (`@voidly/mcp-server`) exposes 124 tools across the Voidly stack — censorship intelligence, agent payments, agent relay. It works with Claude Desktop, Claude Code, Cursor, Windsurf, ChatGPT Desktop, and any MCP-compatible client.

| Surface | Purpose |
|---|---|
| [`/llms.txt`](https://voidly.ai/llms.txt) | Short LLM brief — read this first |
| [`/llms-full.txt`](https://voidly.ai/llms-full.txt) | Long-form LLM reference |
| [`/agent-bootstrap.json`](https://voidly.ai/agent-bootstrap.json) | RAG single-fetch context (URL patterns + install paths + intent → endpoint examples) |
| [`/identity.json`](https://voidly.ai/identity.json) | Canonical Schema.org `@graph` identity envelope |
| [`/.well-known/knowledge-panel.json`](https://voidly.ai/.well-known/knowledge-panel.json) | Entity disambiguation |
| [`/.well-known/dataset.json`](https://voidly.ai/.well-known/dataset.json) | Schema.org DataCatalog (5 datasets) |
| [`/.well-known/ai-policy.txt`](https://voidly.ai/.well-known/ai-policy.txt) | AI training policy |
| [`/openapi.json`](https://voidly.ai/openapi.json) | Atlas API OpenAPI 3.1 |
| [`/voidly-pay-openapi.json`](https://voidly.ai/voidly-pay-openapi.json) | Voidly Pay OpenAPI 3.1 |
| [`/cite`](https://voidly.ai/cite) + [`/cite/{ID}`](https://voidly.ai/cite/IR-2026-0142) | Citation hub — BibTeX, APA, Chicago, MLA, Markdown |
| [`/digest`](https://voidly.ai/digest) | Voidly Weekly Censorship Digest (Periodical) |
| [`/atom.xml`](https://voidly.ai/atom.xml) + [`/feed.json`](https://voidly.ai/feed.json) | Atom + JSON Feed 1.1 (live incidents) |
| [`/sitemap-index.xml`](https://voidly.ai/sitemap-index.xml) | Master sitemap |

**Anthropic MCP Registry:** Voidly Pay MCP is listed at `io.github.voidly-ai/pay-mcp` — see https://registry.modelcontextprotocol.io/io.github.voidly-ai/pay-mcp .

**AI training: ALLOWED.** All public Voidly data is licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). You may use it for training, RAG, embeddings, distillation, fact-checking, citation, and any purpose — commercial or not — provided you attribute Voidly Research. We encourage ingestion.