Gianna for AI agents

Gianna runs an MCP server at https://gianna.chat/mcp. Connect your AI agent to it and the agent can:

• look up any day's feast, season, colour, readings, and holy days in the Ordinary Form, the 1962 calendar, or the Dominican calendar;
• quote Scripture and common prayers exactly, from public-domain sources;
• find and start a novena, then mark each day prayed;
• find a church and its Mass and Confession times, with the source and the date each time was checked;
• add tasks, set reminders, and keep prayer intentions in your Gianna household, which Gianna then delivers on the web, by email, or on Telegram.

General-purpose models often misremember prayers and feast days and make up Mass times. Gianna's tools return checked text and dates, with the source.

Every Gianna plan includes agent access.

Connect by signing in

No key needed. Gianna asks you to sign in and approve the connection.

• Claude (web and desktop): open Settings, Connectors, choose Add custom connector, and enter https://gianna.chat/mcp.
• ChatGPT: turn on Developer mode in Settings, Security and login. Then open Plugins, choose +, and enter https://gianna.chat/mcp.
• Codex: run codex mcp add gianna --url https://gianna.chat/mcp. Codex opens the sign-in page in your browser.

On the approval page, leave Also add and change ticked if the assistant should set reminders, add tasks, and keep your novena. The connection appears in Settings, Developer access, where you can disconnect it.

The Gianna skill

The skill tells an agent when to use Gianna's tools and how: quote prayers exactly, cite Mass time sources, and check that an action succeeded. It is at https://gianna.chat/skill.md in the Agent Skills format.

• Codex: save it as ~/.agents/skills/gianna/SKILL.md.
• Claude Code: save it as ~/.claude/skills/gianna/SKILL.md.

mkdir -p ~/.agents/skills/gianna
curl -o ~/.agents/skills/gianna/SKILL.md https://gianna.chat/skill.md

Coding agents and other clients: use a key

1. Create a key

In Gianna, open Settings, Developer access and create an API key. Tick Allow changes if the agent should add tasks, reminders, intentions, or novenas. Copy the key; it is shown once.

Set it in your shell so the examples below can read it:

export GIANNA_API_KEY=gianna_...

2. Connect your agent

Claude Code

claude mcp add --transport http gianna https://gianna.chat/mcp \
  --header "Authorization: Bearer $GIANNA_API_KEY"

Codex

To use a key instead of signing in, add to ~/.codex/config.toml:

[mcp_servers.gianna]
url = "https://gianna.chat/mcp"
bearer_token_env_var = "GIANNA_API_KEY"

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "gianna": {
      "url": "https://gianna.chat/mcp",
      "headers": { "Authorization": "Bearer ${env:GIANNA_API_KEY}" }
    }
  }
}

VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "gianna": {
      "type": "http",
      "url": "https://gianna.chat/mcp",
      "headers": { "Authorization": "Bearer ${env:GIANNA_API_KEY}" }
    }
  }
}

Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "gianna": {
      "httpUrl": "https://gianna.chat/mcp",
      "headers": { "Authorization": "Bearer $GIANNA_API_KEY" }
    }
  }
}

Any other MCP client

Use the Streamable HTTP transport and the URL https://gianna.chat/mcp, with either the header Authorization: Bearer <your key> or OAuth 2.1 sign-in (discovered from /.well-known/oauth-protected-resource/mcp).

Things to ask

• "What feast is it on Sunday, and what colour are the vestments?"
• "Give me the exact text of the Apostles' Creed in Latin."
• "Start the novena to St Joseph and remind me at 7am each day."
• "When is Confession at St Mary's in Cambridge this Saturday?"
• "Add an intention for my aunt's recovery."
• "Is the Ascension a holy day of obligation in England and Wales this year?"

Tools

A key without a scope does not see that scope's tools. Each tool result includes structuredContent.state_changed; an action happened only when it is true.

Without MCP

• The Gianna API offers the same data and actions as plain JSON over HTTPS: /liturgy/v1, /directory/v1, and /household/v1, each with a public OpenAPI document listed at /.well-known/api-catalog.
• The feast calendars work in any calendar app, with no key.
• A summary for language models is at /llms.txt.

Limits and privacy

• Requests are limited per household per minute. Past the limit you get 429 with Retry-After.
• Changes through an agent act as the account that created the key and appear in Gianna straight away.
• Revoke a key in Settings, Developer access at any time. The agent loses access on its next request.
• Gianna is software. It does not replace a priest, Confession, or spiritual direction.