> For the complete documentation index, see [llms.txt](https://docs.helpyousponsor.com/guides/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.helpyousponsor.com/guides/api-documentation/chatgpt-app-connector.md).

# ChatGPT App Connector

HelpYouSponsor exposes a read-only agent connector for authenticated HYS admins. ChatGPT, Codex, and other MCP clients can use it to search and summarize donor, recipient, sponsorship, donation, dashboard, note, activity, saved-view, and report data that the connected admin is already allowed to view.

Use the production MCP endpoint for public ChatGPT and Codex connections:

```
https://api.helpyousponsor.com/mcp
```

Use staging or a short-lived HTTPS tunnel for private developer-mode tests:

```
https://api-staging.helpyousponsor.com/mcp
```

## What admins can ask

Useful prompts include:

* Find a donor by name or email and summarize their profile, giving, sponsorships, notes, and recent activity.
* Summarize donations for the last 90 days and fetch one donation record.
* Show sponsorship health for a program and fetch one sponsored recipient.
* List saved donor views, donation views, reports, and scheduled reports that can help staff plan follow-up work.
* Show notes and activity for a specific donor or recipient.
* Explain what the connected admin can access in the current HYS workspace.

When a prompt does not include enough information for a record-specific lookup, the assistant should ask a short follow-up question instead of guessing.

## Available read-only tools

The current connector exposes read-only MCP tools including donor lookup, donor list/search/get, recipient/entity list/get, donation list/get/summary, sponsorship summary, notes list, activity-log list, saved filters/listed views, reports list, dashboard snapshot, dashboard brief, forms list, programs list, system context, standard connector-style `search`, and record `fetch`.

Create, update, delete, and archive tools are hidden by default. Mutation tools should only be enabled after explicit scopes, idempotency keys, audit metadata, confirmation UX, and production tests are complete.

## Authentication and permissions

Production ChatGPT connections should authenticate with OAuth account linking. Private developer-mode smoke tests may use a scoped HYS API key or bearer token, but production API keys must not be placed in query strings.

HYS enforces access in layers:

1. Authentication resolves the admin, API key or OAuth token, scopes, and HYS workspace.
2. The primitive registry filters discovery and invocation by primitive scope.
3. Each primitive applies HYS group permission sets such as donor forms, program access, reports, notes, activity logs, and dashboard permissions.
4. Record queries always use the server-derived workspace boundary.

Admins can receive donor PII, custom fields, notes, activity, reports, and saved views when their HYS permissions allow them. The connector does not redact permitted admin data at the app layer; it avoids exposing secrets, request tokens, API keys, payment processor identifiers, trace IDs, and unrelated internal diagnostics.

## MCP discovery endpoints

| Endpoint                                      | Purpose                                                  |
| --------------------------------------------- | -------------------------------------------------------- |
| `GET /mcp/health`                             | Public health check for the MCP server.                  |
| `GET /mcp/manifest`                           | Server metadata, endpoints, and authentication summary.  |
| `POST /mcp`                                   | Primary Streamable HTTP JSON-RPC endpoint.               |
| `GET /mcp/sse`                                | SSE transport compatibility endpoint.                    |
| `POST /mcp/messages`                          | JSON-RPC compatibility endpoint.                         |
| `GET /.well-known/oauth-protected-resource`   | OAuth protected-resource metadata for ChatGPT discovery. |
| `GET /.well-known/oauth-authorization-server` | OAuth authorization-server metadata.                     |

Every unauthenticated MCP request returns an OAuth bearer challenge with the protected-resource metadata URL so compatible clients can discover the auth configuration.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.helpyousponsor.com/guides/api-documentation/chatgpt-app-connector.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.