--- name: gianna description: Use Gianna for sourced Catholic reference questions, including calendars, exact prayers and Scripture, Church teaching, saints, clergy, offices, relics, and Mass or Confession times; for Gianna tasks, reminders and prayer life; or to connect an agent to Gianna. --- # Gianna Gianna is a Catholic assistant with a liturgical calendar for three rites, Scripture and prayers, a novena library, a church directory with sourced Mass and Confession times, Church teaching and Catholic sources, a registry of saints, clergy, offices, relics and bishops, parish groups and jobs, and the user's own household. Catholic reference access is free with an account; household tasks, reminders and prayer tracking need a plan. Its tools are on the Gianna MCP server, `https://gianna.chat/mcp`. ## 1. Check whether Gianna is connected If Gianna's tools (such as `get_liturgical_day`) are available, skip to section 4. If the user already has a Gianna account or API key, go to section 3. Otherwise, offer a free account as described in section 2. Never create an account, choose a password, or enter card details for them. ## 2. Sign up For Catholic reference questions, offer the free account. Explain the plan when the user wants household features: - **A free account** (no card): the liturgy, Scripture, prayers, novenas, churches and their times, saints, relics, lineage, groups and jobs, through you or in the app. Start connecting (section 3): the page where they approve you offers **Create a free account**, so they sign up and approve you in one visit. Without a connection, send them to `https://gianna.chat/app?free=1`. - **A plan**, which adds chat with Gianna, reminders, tasks, routines, prayer intentions and novena tracking, with seven free days first. Send them to `https://gianna.chat/app`, then **Start free**. A plan needs a card; nothing is charged until the seven days are up. They choose a password or continue with Google and accept the Terms. With a password, Gianna emails a link to confirm their address; connecting you does not wait for it. A free account can start a plan later in Settings, Subscription. ## 3. Connect The user signs in on Gianna's own page and approves you; you never see their password. - **If your client supports remote MCP:** add `https://gianna.chat/mcp` and complete its OAuth sign-in. For Codex, run: ```bash codex mcp add gianna --url https://gianna.chat/mcp codex mcp login gianna ``` The client receives the token itself. Claude and ChatGPT setup, and API-key configuration for other clients: https://gianna.chat/docs/agents. - **If the user already has an API key:** use it as a bearer token. No new account or device approval is needed. Keep the key in credential storage. - **Otherwise, sign in with a code** (any agent that can make HTTP requests): 1. `POST https://gianna.chat/oauth/device_authorization` with `{"client_name": ""}`. 2. Tell the user: open the `verification_uri_complete` link (or `https://gianna.chat/activate`) and check the code is `user_code`. They sign in there, or create a free account, and approve you. 3. Every `interval` seconds, `POST https://gianna.chat/oauth/token` with `{"grant_type": "urn:ietf:params:oauth:grant-type:device_code", "device_code": ""}`. `authorization_pending` means wait; `slow_down` means wait longer; `access_denied` or `expired_token` means stop and tell the user. 4. The `access_token` is a key you send as `Authorization: Bearer `. Its scopes and the user's account determine what it permits. Keep it secret, and store it where you keep credentials, not in a file you share. Use the token with the MCP server (`https://gianna.chat/mcp`) or the HTTP APIs in https://gianna.chat/docs/agents. ### Calling MCP with HTTP only After obtaining a token, POST JSON-RPC messages to `https://gianna.chat/mcp` with `Authorization: Bearer `, `Content-Type: application/json`, and `Accept: application/json, text/event-stream`. 1. Send `initialize` with `protocolVersion: "2025-11-25"`, your `clientInfo` (`name` and `version`), and `capabilities: {}`. Check the response, then use its negotiated version as `MCP-Protocol-Version` on subsequent requests. 2. Send `{"jsonrpc":"2.0","method":"notifications/initialized"}`. A `202` response has no body. 3. Send `{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}`. Read the returned descriptions and input schemas; your token determines which tools are visible. 4. Send `tools/call` with the tool's name and arguments. For example: ```json {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_liturgical_day","arguments":{"date":"2026-12-25","calendar":"traditional"}}} ``` Use a distinct request `id` for each request. Read `result.structuredContent` and `result.isError`, or the top-level JSON-RPC `error`. Opening `/mcp` with GET returns `405`; it is a protocol endpoint. REST alternatives and full contracts are at https://gianna.chat/docs/agents. ## 4. Use the tools, not memory - **Feasts, seasons, colours, readings, holy days:** call `get_liturgical_day` with the user's local date. Ask which calendar if it matters (Ordinary Form, traditional 1962, or Dominican); default to the Ordinary Form. - **Prayers:** call `get_prayer`. **Scripture:** call `get_scripture`. Quote the returned text exactly. Do not paraphrase, shorten, or complete a prayer from memory. - **Novenas:** call `find_novena` to find one. With the user's consent, `start_novena`, then `complete_novena_day` each day they pray it. - **Mass and Confession times:** call `get_church_times` with the church name and town, or `find_churches` near a place. Give the source and the date it was checked. If a time is missing, say so. Never invent one. - **Church teaching:** call `find_church_teaching` and cite the document and paragraph. Use `find_catholic_sources` to find sourced Catholic material for a broader question. - **People and offices:** call `find_people`, then `get_person` for a shared profile and its exact links to saint and episcopal records. Call `find_offices`, then `get_office` for current and recorded previous holders. - **Saints, relics, lineage, dioceses:** call `find_saints` or `get_saint`, `find_relics` or `get_relic`, `get_lineage`, and `find_dioceses` for who holds office in a diocese now. These are registry records with sources: a relic record does not certify authenticity, and a lineage record does not rule on validity. **Groups and jobs:** `find_groups` and `find_jobs`. - Keep the `id` of each item in `structuredContent.records`; it never changes. ## 5. Acting for the user - Use `add_reminder`, `add_task`, and `add_prayer_intention` when the user asks to be reminded, to plan something, or to remember an intention. Gianna delivers reminders itself. - Read the result's `status` as well as `state_changed`. `observed` is a read; `applied` with `state_changed: true` reports a change. `no_change` means nothing changed: use the receipt and returned state to determine whether the request was already satisfied or no action was possible. Explain rejection, failure, invalid arguments or missing permission using the returned reason. `verified: true` means Gianna checked the stored outcome. - `replayed: true` is the receipt of an earlier call, not a new action. Report the original outcome without claiming it just ran again. - Send `_meta.idempotencyKey` with each change. If a call fails in transit, retry the same call with the same key. Completed receipts survive server restarts and replay for 24 hours. If the outcome is uncertain or still in progress, read the affected records before doing anything else. Do not switch to a new key or repeat without a key to bypass that result. After 24 hours, check the current state before attempting the action again. - Anything that shares the user's details with someone else needs their approval in Gianna. To ask to join a group, call `add_group_join_request`; to send interest in a job, `add_job_interest_request`. Tell the user Gianna has emailed them and that nothing is sent until they approve it in Settings, Developer access. Check the outcome later with `get_approval_request`. Never say they joined or applied until it shows `approved`. - If a tool says the connection lacks a scope, explain the missing permission. Reconnect with the required scope; household changes need **Also add and change**, or a key with **Allow changes** in Settings, Developer access. - If a tool says the action is part of a Gianna plan, the user has a free account. They can start a plan in Gianna, Settings, Subscription. - The user can see everything you changed in Settings, Developer access, and revoke your access there at any time. - **Adding saints and relics in bulk:** `POST https://gianna.chat/registry/v1/import` with `{"saints": [...], "relics": [...], "dry_run": true}`, then again without `dry_run`. Curators may add and update saints and relics; anyone may add relics, which show as not yet reviewed until a curator checks them. To attach a Saint or cause record to an existing person, supply that person's exact `person_id` and recorded `veneration_status` in the Saint item. Cite a source for every record. Details: https://gianna.chat/docs/agents. ## Boundaries Gianna is software. It does not hear Confession, give absolution, or replace a priest or spiritual director. For pastoral or sacramental needs, point the user to their parish. Gianna's Catholic reference data may be used but not resold or copied in bulk. The feast-day calendar is also published as free feeds anyone can subscribe to: https://gianna.chat/docs/calendars.