Authentication and Church Access
Use the authorization-code flow with PKCE and themcp:read scope. The server
publishes protected resource and authorization server metadata for discovery.
Clients register their OAuth application dynamically and then ask the user to
sign in and approve access.
Use
resource=https://api.thefaithapp.com/mcp in the OAuth flow. The advertised
resource and issuer must match the deployment’s canonical origin. Public
clients use token_endpoint_auth_method=none and S256 PKCE; they do not need
a client secret. Missing credentials receive a bearer authentication
challenge with the protected resource metadata URL.
Each request uses an access token issued for MCP. The signed-in staff account
determines the church and its available records. An argument such as a church
ID cannot grant access to another church. Feature permissions are checked
when reading records, including a previously found result.
The account must have a verified email and an existing church. Church
administrators qualify; other staff need an assigned permission group for that
same church with at least one permission. This connection does not add a new
subscription entitlement or grant broader record permissions.
Member sign-in keys, automation keys, and ordinary dashboard tokens are not
MCP connection credentials. Never paste credentials into a chat prompt.
Claude Code
Add the remote server:/mcp, and authenticate thefaithapp in the browser.
Use a personal or user-scoped connection; credentials should stay outside
source control. See Claude Code MCP setup.
Codex
ChatGPT and Claude
Add the HTTPS server address as a custom remote MCP connection and choose OAuth authentication. Choose automatic client registration if the client offers a registration choice. ChatGPT web exposes this through Plugins > Add custom MCP server; Claude exposes it through Customize > Connectors. Account and workspace policies apply. Follow the product connection guide for sign-in steps. Neither a public directory listing nor a preinstalled plugin is required to evaluate a custom connection.Read-only Tools
Supported domains are
media, categories, devotionals, events,
bulletins, notifications, branches, members, prayer_requests,
gatherings, and donations. Their existing feature permissions still
apply. Sermon media access respects audio and video permissions. Giving
results contain received gifts; donor names and email addresses require donor
detail access. Pastoral and withdrawn prayer requests are excluded, and
anonymous requests do not disclose their author.
Event dates and clock times are returned separately, together with recurrence
details. Gathering start and end times are recurring local clock times, without
an attached calendar date. Interpret these schedules using the church timezone
returned by get_church_context.
search_church_records takes a required domain, an optional text query,
and limit from 1 to 25 (default 8). search accepts a text query across
permitted domains; prefix it with a domain to narrow the lookup, such as
domain:events hope. It returns at most 25 results, with at most five from
each domain. Search is a keyword lookup, not a complete church export.
The search and fetch tools use the compatibility interface for ChatGPT
research workflows: search accepts a query string, and fetch accepts an
id string. Search results include stable IDs, titles, and source URLs.
Fetch returns the title, readable text, source URL, and record metadata.
See OpenAI’s compatibility contract.
Fetch uses identifiers returned by search, such as events:123. It checks
permissions and church ownership again. Results use explicit, bounded fields
rather than full database records. Source URLs require dashboard sign-in;
some open the relevant list workspace rather than opening a record drawer.
Use the returned title or record ID to locate the source in that workspace.
The read-only resource thefaithapp://church/workspace exposes the same
connected-church context for clients that support MCP resources.
The first release does not expose writes, arbitrary HTTP requests, SQL, or
payment actions. Tool annotations declare read-only behavior, while server
authorization controls actual access. An assistant’s claim that a user
approved an action does not grant additional permissions.
Connection Errors
Removing a connection from an AI client may remove only its local credentials.
For server-side invalidation, revoke the MCP authorization through your
platform administrator. The revocation endpoint accepts RFC 7009 form fields
client_id, token, and the optional token_type_hint. It revokes the
matching access token and its refresh credentials, including when the supplied
access token has expired. Do not put a token in a URL, chat prompt, or log.
Previously returned information remains subject to the AI provider’s retention
settings.
Deployment and Validation
The remote server and its OAuth URLs must be reachable over HTTPS. Reverse proxies must preserve the authorization header and route/mcp, OAuth, and
discovery requests to the API. Use the same canonical origin in metadata,
authorization, and token requests.
Apply the API’s MCP database migration before rollout. It creates the client,
consent, and token church-binding tables used by every authorized connection.
Test discovery, browser consent, initialization, tool discovery, permitted
reads, refused reads, and revocation in each intended AI client after deploying.
Local automated tests and SDK/protocol checks do not establish that an
organization has allowed a connection or that a public connector listing
has been approved.