Tutorial: Jokes - Gnist Context

Entertainment

Data source: In-memory curated collection

Overview

Jokes 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-jokes": {
      "url": "https://context.gnist.ai/mcp/jokes/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (5)

`get_random_joke`

Get a random joke. Returns a joke with setup and punchline. For single-type jokes, the full joke is in the setup field. Optionally filter by category — use list_joke_categories() to see valid categories.

Parameter	Type	Required	Description
`category`	any	optional	Filter by category (e.g. Programming, Dad Jokes, Science, Math). Omit for any category.

curl -X POST "https://context.gnist.ai/mcp/jokes/" \
  -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_joke", "arguments": {"category": "Programming"}}}'

import httpx

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

`get_random_jokes`

Get multiple random jokes. Returns a list of unique random jokes. Optionally filter by category.

Parameter	Type	Required	Description
`count`	any	optional	Number of jokes to return (1-20, default 5).
`category`	any	optional	Filter by category. Omit for any category.

curl -X POST "https://context.gnist.ai/mcp/jokes/" \
  -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_jokes", "arguments": {"count": "example"}}}'

import httpx

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

`search_jokes`

Search for jokes by keyword. Searches across setup text, punchlines, and categories. Case-insensitive.

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

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

import httpx

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

`list_joke_categories`

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

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

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/jokes/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {}, 'name': 'list_joke_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/jokes/" \
  -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/jokes/",
    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_jokes to find items, then get_random_joke 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 Jokes provide?

Curated joke database with 120 jokes across 8 categories — get random jokes, search, or browse by category. It exposes 5 tools: get_random_joke, get_random_jokes, search_jokes, list_joke_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 Jokes API return?

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