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.

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 Metadata Documents are both accepted; clients that pre-register a client_id work too.
• Client authentication. none (public clients, the common case) and both client_secret_post and client_secret_basic for confidential ones.
• Scopes. There is one read-only scope, liturgy:read. Clients that ask for unrelated scopes (openid profile, mcp, or nothing) still get a working connection.
• CORS. Preflight is answered and WWW-Authenticate is exposed, so browser-based clients can read the challenge and start the flow.
• Probes. Unauthenticated GET/DELETE on /mcp return the auth challenge rather than a bare 405, so clients that probe before authenticating still discover the flow.

Client config for a key-based deployment

{
  "mcpServers": {
    "estevao": {
      "type": "http",
      "url": "https://<your-host>/mcp",
      "headers": { "X-API-Key": "estevao_your_key" }
    }
  }
}

Extra env: PORT (default 3333), ESTEVAO_MCP_ALLOWED_HOSTS (comma-separated; enables DNS-rebinding protection).

Plugin para Codex, Claude e outros clientes

O repositório inclui um pacote universal em plugins/estevao, com manifests para Codex e Claude Code e uma configuração MCP compartilhada. O pacote aponta para o servidor hospedado, então a conexão usa OAuth e não exige copiar uma API key.

Para Claude Code:

/plugin marketplace add dodopok/estevao-mcp
/plugin install estevao@estevao

Para Codex CLI:

codex mcp add estevao --url https://mcp.caminhoanglicano.com.br/mcp
codex mcp login estevao

Veja o guia visual de integração no portal do desenvolvedor. O mesmo endpoint funciona em qualquer cliente MCP compatível com Streamable HTTP e OAuth 2.1.

Development

npm install
npm run typecheck && npm test    # vitest + msw fixtures, no network
npm run build                    # tsup → dist/index.js + dist/http.js
npm run inspector                # manual testing with the MCP Inspector

# end-to-end against a local estevao-api (docker-compose up in that repo):
SMOKE_KEY=estevao_… npx tsx scripts/smoke.ts

# remote transport (see .env.example for the OAuth variables):
npm run build && node dist/http.js
docker build -t estevao-mcp . && docker run -p 3333:3333 --env-file .env estevao-mcp

Releasing

npm version patch        # bumps package.json AND server.json (version hook), commits + tags
git push --follow-tags
npm publish --access public
mcp-publisher publish    # mcp-publisher login github, first time

The npm version lifecycle hook (scripts/sync-version.ts) keeps server.json in sync and enforces the registry's 100-char description limit. The server's advertised MCP version comes from package.json at build time.

server.json lists both the hosted endpoint (remotes) and the npm package (packages), so registry clients can pick either. Keep the hosted URL in step with the actual deployment.

Alternatively, once GitHub Actions is available with the NPM_TOKEN secret, git push --follow-tags alone triggers the release workflow (npm with provenance + MCP registry via GitHub OIDC).

License

MIT