> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thefaithapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Connect remote AI clients to a church-scoped, read-only TheFaithApp workspace using OAuth.

TheFaithApp exposes a remote Model Context Protocol server at:

```text theme={null}
https://api.thefaithapp.com/mcp
```

It uses Streamable HTTP and the existing TheFaithApp staff OAuth sign-in.
The server runs in the API deployment; connecting does not require a local
TheFaithApp process or a separate MCP application.

For non-technical setup, see [Connect AI Assistants](https://docs.thefaithapp.com/product/connect-ai-assistants.md).

## Authentication and Church Access

Use the authorization-code flow with PKCE and the `mcp: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.

| Route | Purpose |
| - | - |
| `POST /mcp` | MCP initialization, discovery, and tool calls. |
| `GET /.well-known/oauth-protected-resource/mcp` | MCP resource and scope discovery. |
| `GET /.well-known/oauth-authorization-server` | OAuth issuer and endpoint discovery. |
| `POST /oauth/mcp/register` | Register a public MCP OAuth client. |
| `/oauth/authorize` | Existing browser sign-in and explicit consent. |
| `POST /oauth/token` | Exchange an authorization code or refresh token. |
| `POST /oauth/mcp/revoke` | Revoke an issued MCP credential. |

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:

```sh theme={null}
claude mcp add --transport http thefaithapp https://api.thefaithapp.com/mcp
```

Open Claude Code, run `/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](https://code.claude.com/docs/en/mcp).

## Codex

```sh theme={null}
codex mcp add thefaithapp --url https://api.thefaithapp.com/mcp
codex mcp login thefaithapp
```

Complete the browser sign-in and consent flow. An equivalent server entry is:

```toml theme={null}
[mcp_servers.thefaithapp]
url = "https://api.thefaithapp.com/mcp"
scopes = ["mcp:read"]
```

Keep OAuth credentials in the client's credential storage. See
[OpenAI's MCP configuration guide](https://learn.chatgpt.com/docs/extend/mcp).

## 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](https://docs.thefaithapp.com/product/connect-ai-assistants.md) for
sign-in steps. Neither a public directory listing nor a preinstalled plugin
is required to evaluate a custom connection.

## Read-only Tools

| Tool | Purpose |
| - | - |
| `get_church_context` | Identify the connected church and available read areas. |
| `get_church_overview` | Return a summary limited to the caller's permissions. |
| `search_church_records` | Search a supported church data area with bounded results. |
| `search` | Return source-linked results for a text query. |
| `fetch` | Read an authorized result by its returned identifier. |

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](https://developers.openai.com/api/docs/mcp).

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

| Result | What to check |
| - | - |
| `401` | Sign in again; the token may be missing, invalid, revoked, or expired. |
| `403` | Check the granted MCP scope and the staff account's church access. |
| Tool reports denied access | Check the feature permission for that record area. |
| Empty search results | Try a narrower query and confirm the area is supported. |
| `429` | Wait before retrying; the connection is rate limited. |

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.