Tutorial: Random Facts - Gnist Context

Reference

Data source: In-memory curated collection

Overview

Random Facts wraps In-memory curated collection, handling authentication, pagination, and rate limits for you. This tutorial covers all 5 tools with working code examples you can copy and run.

Prerequisites

Sign up at https://context.gnist.ai/signup for a free API key (100 calls/day).
Choose your integration method: MCP protocol or REST API.

Connect via MCP

Add to your MCP client config (Claude Desktop, Cursor, etc.):

MCP Config

{
  "mcpServers": {
    "gnist-random-facts": {
      "url": "https://context.gnist.ai/mcp/random-facts/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (5)

`get_random_fact`

Get a random interesting fact. Returns a fact with its category and source attribution. Optionally filter by category.

Parameter	Type	Required	Description
`category`	any	optional	Filter by category (e.g. Science, History, Space). Omit for any category.

curl -X POST "https://context.gnist.ai/mcp/random-facts/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_random_fact", "arguments": {"category": "Science"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/random-facts/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'category': 'Science'}, 'name': 'get_random_fact'}},
)
print(resp.json())

`get_random_facts`

Get multiple random facts at once. Returns a list of facts, optionally filtered by category. Facts are sampled without repeats.

Parameter	Type	Required	Description
`count`	any	optional	Number of random facts to return (default: 5, max: 50).
`category`	any	optional	Filter by category (e.g. Science, History, Space). Omit for any category.

curl -X POST "https://context.gnist.ai/mcp/random-facts/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_random_facts", "arguments": {"count": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/random-facts/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'count': 'example'}, 'name': 'get_random_facts'}},
)
print(resp.json())

`search_facts`

Search for facts by keyword. Searches across fact text, categories, and source attributions. Case-insensitive.

Parameter	Type	Required	Description
`query`	string	required	Search keyword — matches fact text, category, or source.
`max_results`	any	optional	Maximum number of results (default: 20, max: 100).

curl -X POST "https://context.gnist.ai/mcp/random-facts/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "search_facts", "arguments": {"query": "renewable energy"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/random-facts/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'query': 'renewable energy'}, 'name': 'search_facts'}},
)
print(resp.json())

`list_fact_categories`

List all available fact categories. Returns the category names that can be used to filter random facts.

curl -X POST "https://context.gnist.ai/mcp/random-facts/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "list_fact_categories", "arguments": {}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/random-facts/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {}, 'name': 'list_fact_categories'}},
)
print(resp.json())

`report_feedback`

Report a bug, feature request, or general feedback for this data source. Use this when something doesn't work as expected, when you'd like a new feature, or when you have suggestions for improvement. Args: feedback: Describe the issue or suggestion. feedback_type: One of 'bug', 'feature_request', or 'general'.

Parameter	Type	Required	Description
`feedback`	string	required
`feedback_type`	string	optional	(default: `general`)

curl -X POST "https://context.gnist.ai/mcp/random-facts/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "report_feedback", "arguments": {"feedback": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/random-facts/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'feedback': 'example'}, 'name': 'report_feedback'}},
)
print(resp.json())

Common Patterns

Search then retrieve
Use search_facts to find items, then get_random_fact to get full details. This two-step pattern is common for exploring data before drilling down.

Pagination
Several tools support limit, offset, or page parameters. Start with small limits during development, then increase for production queries.

FAQ

What data does Random Facts provide?

Curated database of 150+ interesting facts across 12 categories — science, history, nature, space, and more. It exposes 5 tools: get_random_fact, get_random_facts, search_facts, list_fact_categories, report_feedback.

What do I need to get started?

A Gnist API key (free tier: 100 calls/day). Sign up at https://context.gnist.ai/signup.

What format does the Random Facts API return?

JSON, via either MCP protocol (JSON-RPC 2.0) or REST API.