Tutorial: Country Information

Reference

Data source: Embedded (ISO 3166)

Overview

Country Information wraps Embedded (ISO 3166), 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-country-info": {
      "url": "https://context.gnist.ai/mcp/country-info/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (5)

`get_country`

Get detailed information about a country by ISO code (alpha-2 or alpha-3). Args: code: ISO 3166-1 alpha-2 (e.g. "NO") or alpha-3 (e.g. "NOR") country code. Returns: Dictionary with country details including capital, population, currencies, and more.

Parameter	Type	Required	Description
`code`	string	required

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

import httpx

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

`search_countries`

Search countries by name (case-insensitive partial match). Args: query: Search string to match against country names. limit: Maximum number of results to return (default 10). Returns: Dictionary with count and list of matching countries.

Parameter	Type	Required	Description
`query`	string	required
`limit`	integer	optional	(default: `10`)

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

import httpx

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

`list_countries_by_region`

List all countries in a given region. Args: region: Region name — one of Africa, Americas, Asia, Europe, Oceania. Returns: Dictionary with region, count, and list of countries.

Parameter	Type	Required	Description
`region`	string	required

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

import httpx

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

`get_country_stats`

Get summary statistics about countries in the database. Returns: Dictionary with total countries, UN members, landlocked count, breakdown by region, and total population.

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

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/country-info/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {}, 'name': 'get_country_stats'}},
)
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/country-info/" \
  -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/country-info/",
    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_countries to find items, then get_country 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 Country Information provide?

Detailed information on world countries — codes, capitals, population, currencies, languages, and more. It exposes 5 tools: get_country, search_countries, list_countries_by_region, get_country_stats, 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 Country Information API return?

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