For developers

GemZen tools for AI agents

Give your chatbot, voice agent or 3D avatar real oracle capabilities — tarot draws, birth charts, rune casts, compatibility and daily guidance — through the Model Context Protocol or plain REST. One endpoint, 17 tools, millisecond answers.

Request an API key Quickstart

Three ways in

Same tools, same quota — pick the transport that fits your stack.

MCP for agent platforms

Native Model Context Protocol over Streamable HTTP. Works out of the box with Vapi, ElevenLabs Agents, LiveKit, Pipecat, the OpenAI Realtime API, Inworld and any MCP-capable framework. Point it at the endpoint, send your key as a bearer token, and every tool is discovered automatically.

https://gemzen.app/api/mcp

Connectors for Claude & ChatGPT

Add GemZen as a custom connector and sign in with your GemZen account — OAuth handles the rest. ChatGPT deep research is supported through the standard search + fetch contract.

Claude → Settings → Connectors → Add custom connector

REST for everything else

Game engines, Convai-style action APIs, plain backends: every tool is mirrored as a JSON endpoint with a published JSON Schema. Business denials map to familiar HTTP status codes.

POST https://gemzen.app/api/v1/tools/{tool}

Quickstart

From key to first reading in under a minute.

1 · Discover the tools

curl https://gemzen.app/api/v1/tools

2 · Call one over REST

curl -X POST https://gemzen.app/api/v1/tools/card_of_day \
  -H "Authorization: Bearer gmzk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject_id": "your-user-123"}'

3 · Or connect via MCP

{
  "mcpServers": {
    "gemzen": {
      "url": "https://gemzen.app/api/mcp",
      "headers": { "Authorization": "Bearer gmzk_YOUR_KEY" }
    }
  }
}

A birth chart computes in ~5 ms. Daily tools are deterministic per user per day — cache them for 24 hours and save your quota.

The 17 tools

Generated from the live tool registry — what you see here is exactly what your agent discovers.

Reference content

Curated meanings for every card, rune, hexagram, crystal and phase — instant, deterministic reads.

Tool	What it does
tarot_card_lookup	Full meaning bundle for ONE tarot card (keywords, upright, reversed, symbolism, advice) by name, e.g. "The Fool" or "Three of Cups". For the whole deck use tarot_deck_list.
tarot_deck_list	Compact list of the full 78-card deck (name, arcana, suit, number, keywords). This is the sanctioned bulk endpoint — use it instead of looking cards up one by one.
rune_lookup	Meaning, mythology and advice for one of the 24 Elder Futhark runes by name, e.g. "Fehu".
iching_hexagram_lookup	Judgment, image, interpretation, advice and all six changing-line meanings for one I Ching hexagram (1–64).
lenormand_card_lookup	Meaning, timing and advice for one of the 36 Lenormand cards, by number (1–36) or name.
crystal_recommend	Recommend crystals for an intent (e.g. "calm", "focus", "love"), chakra, or element — with properties, use and care.
moon_phase_meaning	Interpretive guidance for a moon phase. Pass a date (YYYY-MM-DD) to get that day's ACTUAL phase (ephemeris-computed) with its meaning, or a phase name directly.
fetch	Fetch the full text of one GemZen corpus document by the id returned from search.

Charts & computation

Real ephemeris math computed in milliseconds: natal charts, synastry, transits, numerology, biorhythms.

Tool	What it does
birth_chart	Compute a full natal chart: planet signs/houses/retrogrades, Ascendant, Midheaven, house cusps and strongest aspects. Requires birth date, latitude/longitude and IANA timezone (ask the user for their birth city and resolve coordinates yourself).
astro_compatibility	Compare two birth charts: compatibility score (0–100), harmony/passion/challenge/growth breakdown, key relationship themes and strongest inter-aspects.
current_sky	Planetary positions, retrogrades, moon phase and moon sign for any date-time (defaults to now). The 'what's happening in the sky' tool.
numerology_profile	Life Path, Expression, Soul Urge and Personality numbers from full name + birth date, plus the current Personal Year with its meaning.
biorhythm	Physical, emotional and intellectual cycle values (−100..100) for a birth date on a target date, plus critical-day flags.

Daily experience

Deterministic daily draws — the same user gets the same card all day. Safe to cache for 24 hours.

Tool	What it does
card_of_day	Deterministic tarot card of the day with its full meaning. The same subject_id gets the same card all day (UTC) — safe to cache for 24h.
daily_guidance	Composed daily snapshot: today's real moon phase (ephemeris), universal day number, personal day number (if birth_date given) and the card of the day. Deterministic per day + subject — safe to cache for 24h.

AI readings

Full AI-written interpretations of live draws. Metered against your plan’s AI budget.

Tool	What it does
oracle_reading	Draw a spread (tarot 1 or 3 cards, 3 runes, or an I Ching cast) for a question and return an AI-written interpretation. Metered against the AI budget — requires an AI-enabled plan.

Corpus search

search + fetch over the GemZen knowledge corpus — the pair ChatGPT deep research expects.

Tool	What it does
search	Search GemZen's curated oracle reference corpus (tarot, runes, I Ching, Lenormand, crystals, moon phases, chakras, ogham, numerology, zodiac). Returns result ids for fetch.

Plans

Start free, scale when your users do.

Free Dev

Free

·500 calls / day
·10 calls / minute
·All content, compute & daily tools
·Corpus search + fetch
·Attribution required

For evaluation and prototypes.

Partner

For launched apps

·50,000 calls / day
·120 calls / minute
·Everything in Free Dev
·AI oracle readings included
·Email support

For live products with real users.

Commercial

Custom

·Custom volume & burst
·Custom AI budget
·Usage statements
·License agreement & SLA

For platforms and high-volume integrations.

House rules

1.Show the attribution. Every response carries a _license.attribution line — display it wherever GemZen content reaches your users.
2.Surface the disclaimer. Readings are for reflection and entertainment — the payload includes the exact wording; pass it through.
3.Don't hoard or train. Cache up to 24 hours (daily tools are built for it), no bulk redistribution, no training models on responses.
4.Use the bulk paths. tarot_deck_list and search exist so you never need to crawl item lookups one by one.

Ready to give your agent an inner life?

Tell us what you're building and we'll set you up with a free developer key — usually the same day.

Request an API key