estevao-mcp

MCP (Model Context Protocol) server for the Estêvão API — the liturgical engine behind the Ordo app. Gives Claude and any MCP client accurate Anglican liturgical data: calendar (with real precedence rules), lectionary readings, and the fully assembled Daily Office across multiple editions of the Book of Common Prayer / Livro de Oração Comum.

Quick start

Hosted (no key to manage) — sign in with your Google/e-mail account when the browser opens:

claude mcp add --transport http estevao https://mcp.caminhoanglicano.com.br/mcp   # Claude Code
codex mcp add estevao --url https://mcp.caminhoanglicano.com.br/mcp               # Codex CLI

Other clients: see Connecting any MCP client.

Local (stdio) — you need an Estêvão API key (estevao_…):

claude mcp add estevao --env ESTEVAO_API_KEY=estevao_your_key -- npx -y estevao-mcp

Or in .mcp.json / Claude Desktop config:

{
  "mcpServers": {
    "estevao": {
      "command": "npx",
      "args": ["-y", "estevao-mcp"],
      "env": { "ESTEVAO_API_KEY": "estevao_your_key" }
    }
  }
}

Then ask things like "what are the readings for next Sunday?", "assemble tonight's Compline" or "compare Christmas in the 1662 and 2019 prayer books".

Tools

Dates accept YYYY-MM-DD, today or next-sunday. Every tool takes an optional prayer_book (default loc_2015); all tools are read-only. Prayer book codes are validated by the API rather than pinned in this server, so editions added upstream work without a release here — list_prayer_books always shows the current catalogue.

Resources & prompts

• Resources: ordo://prayer-books, ordo://bible-versions, ordo://today, plus templates ordo://day/{date}, ordo://explain/{date} (the decision trail), ordo://office/{date}/{office_type} (markdown) and ordo://calendar/{year}/key-dates.
• Prompts (strictly factual): build_liturgy_sheet (print-ready boletim), explain_feast (history, precedence, color), explain_why (why this reading/saint/colour, answered from the engine's decision trail rather than inferred), compare_traditions (side-by-side across editions).

Editorial note: this server intentionally exposes only factual liturgical data and faithful document assembly. It does not (and will not) ship prompts that generate sermons, homilies or devotional reflections.

Environment variables

Per-book preferences

The date-scoped tools take a preferences object forwarded to the API, which unlocks the per-edition options the Ordo app exposes — the Coverdale psalter on the English books ({ "psalm_translation": "coverdale" }), monthly vs appointed psalm cycles, canticle and opening-sentence choices, family-rite variants. The accepted keys differ per book, so call get_prayer_book_preferences first rather than guessing.

Languages

Liturgical content always stays in the prayer book's own language (a 1662 office is English, LOC 2015 is Portuguese). Labels generated by the server — office titles, Season/Tempo/Tiempo, comparison headings — automatically follow the book's language, and can be overridden per call (language param) or globally (ESTEVAO_LANGUAGE).

Remote server (Streamable HTTP + OAuth)

The same server runs as a remote MCP endpoint (POST /mcp, stateless Streamable HTTP). Deployed with OAuth enabled, users connect with a browser sign-in instead of pasting a key:

claude mcp add --transport http estevao https://mcp.caminhoanglicano.com.br/mcp
codex mcp add estevao --url https://mcp.caminhoanglicano.com.br/mcp && codex mcp login estevao

The client discovers the authorization server, registers itself, opens the consent screen, and the user signs in with the same Google/e-mail account they use in the developer portal. The server then provisions an Estêvão API key for that account, encrypts it at rest and uses it for every upstream call — the user never sees or handles a key, and the client's token is never forwarded upstream.

Auth modes

The mode is chosen by environment, and resolved per request in this order:

1. Single-key (personal deployment): ESTEVAO_API_KEY set on the server. Optionally set ESTEVAO_MCP_TOKEN to require Authorization: Bearer <token> from clients.
2. API key (unchanged, for existing integrations): the caller sends its own key in X-API-Key (or Authorization: Bearer estevao_…). Disable with ESTEVAO_MCP_ALLOW_API_KEY_HEADER=false.
3. OAuth 2.1 (recommended for public deployments): the caller sends an access token issued by this server. Enabled when the OAuth variables below are all set.

OAuth configuration

Setting only some of these is a configuration error and the server refuses to start, rather than silently falling back to key-only mode. The Postgres schema is created on boot.

Same-origin sign-in (required on mobile and Safari)

By default the Firebase Web SDK runs its sign-in helper on <project>.firebaseapp.com, a different origin from this server. Safari's ITP (16.1+), Firefox and the in-app browsers used by mobile assistants block the cross-origin round trip that flow needs: the user picks a Google account and then nothing happens. So this server reverse-proxies /__/auth/* to the Firebase helper and points the consent screen at its own origin, which is the fix Firebase documents for it. Sign-in uses a full-page redirect rather than a popup, for the same reason.

Two one-time console steps make this work:

1. Firebase Console → Authentication → Settings → Authorized domains: add the MCP host.
2. Google Cloud Console → APIs & Services → Credentials → the Web OAuth 2.0 client used by Firebase: add https://<mcp host>/__/auth/handler to Authorized redirect URIs.

Set MCP_FIREBASE_AUTH_PROXY=false to go back to the stock cross-origin behaviour.

Diagnosing a failed sign-in

Sign-in runs in the user's browser, so a failure there reaches no log by itself. The consent screen posts beacons to /oauth/diagnostics, which the server writes to stderr:

[consent] rendered request=… client=Claude
[consent] stage=loaded pending=false storage=true ua=…
[consent] stage=redirect-start request=… ua=…
[consent] stage=redirect-lost request=… ua=…     ← came back from Google, state was lost
[consent] stage=redirect-error code=auth/…       ← Firebase rejected the sign-in
[consent] approve failed request=… error=…       ← sign-in worked, key provisioning did not

Only error codes and flags are reported — never tokens or credentials.