Getting started
Open Today. The date follows the timezone on this device until you save another timezone in Settings. Reading links go to the USCCB. Reflections are labeled.
Authentication
The website uses a session cookie. The connector does not accept that cookie. On Connect with Muse, create one API token and send it as Authorization: Bearer or X-API-Key. It works on the first request, expires in 90 days, and can be revoked. Five active tokens per account. Do not put the key in the JSON body. ChatGPT and other MCP hosts: paste the token where the host asks for an API key or Bearer token so it is sent as Authorization: Bearer or X-API-Key on tools/call, never inside JSON arguments. Website session cookies do not work and are rejected. list_commitments, create_commitment, update_commitment, delete_commitment, and personal novena tools require that header. Public calendar tools work without it but omit private data. A missing or invalid token fails closed as unauthorized.
REST
GET /api/schema lists tools. POST /api/connector accepts { "action", "arguments" }. GET /openapi.json is the OpenAPI description. GET /api/health is a liveness check.
MCP
POST /api/mcp speaks Model Context Protocol JSON-RPC over streamable HTTP (protocol 2025-03-26): initialize, tools/list, tools/call, and ping. The server is stateless. GET /api/mcp returns a short description. GET /llms.txt is a plain-language map for assistants.
Tools
- get_today — token optional. Morning briefing for a civil date: U.S. Roman calendar, obligation, fast and abstinence, the day's saints, reading citations, the day's Rosary mysteries and Marian prayer, the Pope's monthly intention, the next holy day and season, a labeled reflection, and the caller's commitments and novenas when authenticated.
- get_tomorrow — token optional. Evening look-ahead: tomorrow's celebration, the next seven highlighted days, commitments, and novenas.
- get_week — token optional. Personalized Catholic week: upcoming Sunday, each of the next seven days (important ones flagged), holy days, fast and abstinence days, commitments, and novenas.
- get_mass_companion — token optional. Mass preparation for a date, defaulting to the coming Sunday. Citations and USCCB links only. No commentary and no copyrighted lectionary text. Host assistants must relay citations and links without adding commentary or pasting full readings.
- lectionary_for — token optional. Free read. Ordinary Form celebration for one civil date: rank, title, obligation, liturgical color when known, and reading citations with USCCB links. Citations and links only. No commentary and no copyrighted lectionary text. Not a Catholic Church, Vatican, or USCCB product.
- feast_schedule — token optional. Free read. Ordered feast rows for 1–90 civil days (default 30). Each row is date, title, rank, and obligation only. No commentary. Not a Catholic Church, Vatican, or USCCB product.
- list_upcoming — token optional. Highlighted liturgical days over the next 1–30 days, plus the caller's commitments when authenticated.
- list_commitments — token required. List the signed-in user's Catholic commitments.
- create_commitment — token required. Create a commitment that can appear in the morning and evening briefings.
- update_commitment — token required. Update one of the signed-in user's commitments.
- delete_commitment — token required. Delete one of the signed-in user's commitments.
- list_novenas — token optional. Catalog of novenas, suggested dates, and the caller's progress when authenticated.
- start_novena — token required. Start a catalog novena. Reminders stay inside the two daily briefings.
- get_novena_status — token required. Progress for the signed-in user's novenas, or one run id.
- complete_novena_day — token required. Mark today's novena prayer complete. Future and missed days are not auto-completed.
- get_catholic_explanation — token optional. Reviewed answer distinguishing official teaching, history, and devotion. Unlisted questions return uncertainty rather than a generated doctrine.
- get_settings — token required. The signed-in user's timezone, calendar, and briefing preferences.
- update_settings — token required. Update timezone, calendar, briefing times, delivery channels, interests, or consent.
Errors and limits
Errors use unauthorized, not_found, invalid_argument, rate_limited, or unavailable. The limit is 60 requests a minute and 2,000 a day per token, or per IP hash when no token is sent. A 429 includes Retry-After.
Example
curl -X POST "$ORIGIN/api/connector" -H "content-type: application/json" -d '{"action":"get_today","arguments":{"timeZone":"America/New_York"}}'
With a token, the same call includes your commitments and novenas. Without one, those arrays are empty.
Reminders
Each profile stores a timezone and two local times. A dispatch checks whether that local time has passed. The in-app channel records once per user, date, and slot. Email and web push are attempted from the scheduled time until three hours later, once per slot: each delivery is claimed in the database before it is sent, so overlapping dispatch runs never send twice. Email needs RESEND_API_KEY and RESEND_FROM; push needs VAPID_PUBLIC_KEY and VAPID_PRIVATE_KEY. GET or POST /api/reminders/dispatch requires Authorization: Bearer $CRON_SECRET. If the secret is unset, the route refuses to run. Opening the app also records an in-app briefing that is already due, and the unique key prevents a duplicate.
Environment
Production injects DATABASE_URL and auth credentials. Optional: CRON_SECRET, RESEND_API_KEY, RESEND_FROM, READINGS_API_BASE. The preview needs none of them. See the .env.example shipped with the project. Never put a real secret in the client.
Connection procedure for Muse
1. Publish the app on HTTPS. 2. Sign in and create a token. 3. Submit at muse.ai/platform with the MCP URL, this documentation URL, the privacy and terms URLs, support@agentstructure.ai, and the 512 icon. 4. Tell Muse the authentication method is an API key. 5. Paste the token when Muse asks for it. OAuth with PKCE is not offered.