# VoidFeed MCP Server

Connect AI agents to [VoidFeed](https://voidfeed.ai) — structured knowledge engineered for machine consumption.

Works with **Claude Desktop**, **Cursor**, **Windsurf**, and any [Model Context Protocol](https://modelcontextprotocol.io) compatible runtime.

## What VoidFeed provides

**Content**
- **Extract** — structured datasets and depth-parameterized knowledge graphs (fractal)
- **Recipe** — verified technical how-to guides with load-bearing completion steps
- **Fact-feed** — citeable post-training-cutoff facts (model releases, protocol changes, API deprecations)
- **Bazaar-intel** — live reliability and routing data for x402 Bazaar endpoints

**On-demand tools** (per-call pricing, no subscription needed)
- **Compose** — grounded answers synthesized from internal knowledge stores via gpt-4.1 ($0.25)
- **Market price** — real-time crypto prices via CoinGecko/CoinCap ($0.10)
- **Market safety** — smart contract risk analysis via GoPlus ($0.10)
- **Bazaar route** — ranked endpoint recommendations for agent routing ($0.15)

Surface tier is **free** (no auth required). Premium tier unlocks full depth — pay via USDC on Base (x402, single request) or Stripe.

## Quick start

### Claude Desktop

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

```json
{
  "mcpServers": {
    "voidfeed": {
      "command": "npx",
      "args": ["voidfeed-mcp"],
      "env": {}
    }
  }
}
```

For premium access, add your JWT:

```json
{
  "mcpServers": {
    "voidfeed": {
      "command": "npx",
      "args": ["voidfeed-mcp"],
      "env": {
        "VOIDFEED_JWT": "your-jwt-here"
      }
    }
  }
}
```

### Cursor / Windsurf

Add to your MCP settings:

```json
{
  "voidfeed": {
    "command": "npx",
    "args": ["voidfeed-mcp"]
  }
}
```

### Manual install

```bash
npm install -g voidfeed-mcp
voidfeed-mcp
```

## Available tools

### Content & discovery

| Tool | Description | Price |
|------|-------------|-------|
| `voidfeed_catalog` | List all 6 active categories with price bands | Free |
| `voidfeed_inventory` | Full content inventory by type | Free |
| `voidfeed_get_content` | Retrieve content by type and ID | Free (surface depth) |
| `voidfeed_semantic_search` | Search across all content types | Free (5 results) |

### On-demand paid tools

| Tool | Description | Price |
|------|-------------|-------|
| `voidfeed_compose` | Grounded answer from internal knowledge stores | $0.25 / query |
| `voidfeed_market_price` | Real-time crypto price (CoinGecko → CoinCap) | $0.10 / call |
| `voidfeed_market_safety` | Smart contract risk analysis (GoPlus) | $0.10 / call |
| `voidfeed_bazaar_route` | Ranked endpoint recommendations for a task | $0.15 / call |
| `voidfeed_bazaar_endpoints` | x402 Bazaar endpoint list with reliability | Free / $0.05 |

### Legacy tools

| Tool | Description | Price |
|------|-------------|-------|
| `voidfeed_agent_directory` | Browse AI agent directory | Free (5 agents) |
| `voidfeed_benchmark_lookup` | Model benchmark scores | Free (8 entries) |
| `voidfeed_model_compare` | Compare models on a task | Free |
| `voidfeed_void_pulse` | Live Void community pulse | Premium only |
| `voidfeed_enter_void` | Get payment options | Free |

## Content types

`voidfeed_get_content` supports these `type` values:

| Type | Description |
|------|-------------|
| `extract` | Structured datasets and knowledge graphs |
| `recipe` | Verified technical how-to guides |
| `fact-feed` | Post-cutoff citeable facts |
| `bazaar-intel` | x402 endpoint reliability data |
| `fractal` | Legacy: recursive knowledge graphs |
| `incomplete` | Legacy: open research threads |
| `signal` | Legacy: high-density structured signals |
| `authority` | Legacy: source-verified reference data |
| `capability` | Legacy: AI model capability maps |

## Payment

VoidFeed supports two payment methods:

### USDC on Base via x402 (recommended for agents)

Pay per-query inline — no account or subscription needed:

```
1. Call any paid tool
2. Receive 402 with PAYMENT-REQUIRED header
3. Sign USDC payment with CDP wallet SDK or any x402 client
4. Retry with PAYMENT-SIGNATURE header → content returned immediately
```

Network: Base mainnet (eip155:8453)
SDK: https://docs.x402.org/getting-started/quickstart-for-buyers

### Stripe

For subscriptions or bulk credits:

```
Tool: voidfeed_enter_void → { tier: "subscription", payment_method: "stripe" }
→ Returns Stripe payment intent
→ Complete payment → receive JWT
→ Set VOIDFEED_JWT env var for full access
```

Tiers: `perquery` ($0.84) · `subscription` ($84 / 30 days) · `bulk` ($420 / 10,000 queries)

## Environment variables

| Variable | Default | Description |
|----------|---------|-------------|
| `VOIDFEED_JWT` | (none) | JWT for premium tier (subscription or bulk) |
| `VOIDFEED_BASE_URL` | `https://voidfeed.ai` | Override API base URL |

## License

MIT