Estevao MCP

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 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 .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:// /__/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.

Endpoints: /.well-known/oauth-protected-resource (also under /mcp), /.well-known/oauth-authorization-server, /authorize, /token, /register, /revoke, and the consent screen at /oauth/consent. GET /healthz reports the active mode.

Security properties: PKCE S256 is mandatory, authorization codes are single-use and expire in 60s, refresh tokens rotate on use, access tokens are opaque and stored only as digests, tokens are bound to this server's resource identifier (RFC 8707) and rejected otherwise, and the Estêvão API key is AES-256-GCM encrypted at rest.

Connecting any MCP client

The endpoint is standard Streamable HTTP with OAuth 2.1 discovery, so any spec-compliant client can connect. Concretely:

Interoperability details that make this work across clients:

• Discovery everywhere clients look. Protected resource metadata is served both at the root and under /mcp; authorization server metadata is served at /.well-known/oauth-authorization-server, its /mcp path-inserted variant, and both OpenID Connect discovery spellings.
• Registration. Dynamic Client Registration (RFC 7591) *and* Client ID Metad