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

# Agent Primitives

> Use Gratona MCP tools and primitive APIs from ChatGPT, Codex, and other agent clients.

Gratona exposes a read-only agent surface for authenticated admins. Agent
clients can search and summarize donor, recipient, sponsorship, donation,
dashboard, note, activity, saved-view, and report data that the connected admin
is already allowed to view in their Gratona workspace.

The same backend primitive registry powers REST, MCP, and the repo-local CLI.
Do not build integrations that pass a user-supplied `client_id`; Gratona derives the
workspace boundary from the authenticated admin or API key and applies primitive
scopes plus Gratona permission sets for every request.

## Current MCP Tool Surface

| Tool | What it does | Required access |
| - | - | - |
| `search` | Standard connector-style search across permitted donor and recipient records. | Search scope plus donor-form or program permission. |
| `hys_donors_lookup` | Finds a donor by name, email, or text and returns a bounded donor snapshot. | Donor search/get scopes plus donor-form permission. |
| `hys_records_get` | Fetches a returned `donor:{id}`, `entity:{id}`, or `donation:{id}` record. | Matching primitive scope plus record-level Gratona permission. |
| `hys_donors_list` | Lists permitted donors with filters, pagination, and optional includes. | Donor list scope plus donor-form permission. |
| `hys_donors_search` | Searches permitted donors. | Donor search scope plus donor-form permission. |
| `hys_donors_get` | Fetches one permitted donor with optional related records. | Donor get scope plus donor-form permission. |
| `hys_entities_list` | Lists permitted recipients/entities by program, visibility, and sponsorship state. | Entity list scope plus program permission. |
| `hys_entities_get` | Fetches one permitted recipient/entity. | Entity get scope plus program permission. |
| `hys_donations_list` | Lists permitted donation records. | Donation list scope plus donation/report visibility. |
| `hys_donations_get` | Fetches one permitted donation record. | Donation get scope plus donation/report visibility. |
| `hys_donations_summary` | Summarizes giving in a permitted date range. | Donation summary scope plus donation/report visibility. |
| `hys_sponsorships_summary` | Summarizes sponsorship health across permitted donors and programs. | Sponsorship scope plus donor and program visibility. |
| `hys_notes_list` | Lists full permitted notes for a donor or recipient. | Notes scope plus target record permission. |
| `hys_activity_logs_list` | Lists permitted activity history and metadata for a donor or recipient. | Activity-log scope plus target record permission. |
| `hys_filters_list` | Lists saved views and report filters available to the admin. | Filter scope plus module/form/program permission. |
| `hys_reports_list` | Lists saved report definitions, schedules, and recipient metadata available to the admin. | Report scope plus report/module/form/program permission. |
| `hys_dashboard_snapshot` | Returns high-level workspace metrics and signals. | Dashboard scope plus filtered aggregate visibility. |
| `hys_dashboard_brief` | Returns a concise board-prep or staff-summary brief. | Dashboard scope plus filtered aggregate visibility. |
| `hys_forms_list` | Lists forms the admin can use for donor or program workflows. | Forms scope plus form/program permission. |
| `hys_programs_list` | Lists programs visible to the admin. | Program scope plus program permission. |
| `hys_system_context` | Shows connected admin, workspace, scopes, and permission keys without secrets. | System context scope. |
| `hys_snapshot_widget_render` | Renders a compact ChatGPT snapshot from already fetched permitted data. | Render-only; it does not fetch broader data. |

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.

## ChatGPT And Codex

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

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

Use staging or a short-lived HTTPS tunnel for private Developer Mode tests:

```text theme={null}
https://api-staging.helpyousponsor.com/mcp
```

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

Useful admin prompts:

* "Find Mattie Charles and summarize her profile, giving, sponsorships, notes, and recent activity."
* "Summarize donations for the last 90 days and fetch one donation record."
* "Show sponsorship health for Education and one sponsored recipient."
* "List saved views and reports that would help me plan today's follow-up work."
* "Show notes and activity for donor 26303."
* "What can I access in this Gratona 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.

## MCP Endpoints

| Endpoint | Purpose |
| - | - |
| `GET /mcp/health` | Public health check for the MCP server. |
| `GET /mcp/manifest` | Server metadata, public 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.

## Auth And Permissions

Gratona enforces access in layers:

1. Authentication resolves the admin, API key or OAuth token, scopes, and Gratona
   workspace.
2. The primitive registry filters discovery and invocation by primitive scope.
3. Each primitive applies Gratona 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 Gratona 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.

## REST Primitive API

Use REST when you need direct HTTP access from scripts or services.

* Base URL: `https://api.helpyousponsor.com`
* Auth header: `X-HYS-API-Key: hys_...`
* Discovery: `GET /v3/primitives`
* Primitive schema: `GET /v3/primitives/{name}/schema`
* Invoke: `POST /v3/primitives/{name}/invoke`
* Dry-run validation: `POST /v3/primitives/{name}/validate`

Example:

```bash theme={null}
curl --request POST \
  --url https://api.helpyousponsor.com/v3/primitives/donors.search/invoke \
  --header 'Content-Type: application/json' \
  --header 'X-HYS-API-Key: hys_your_key_here' \
  --data '{
    "query": "smith",
    "limit": 10
  }'
```

## Schema Discovery

Agents can inspect the Gratona data model surface when granted `schema:read`.

* `GET /v3/schema/models`
* `GET /v3/schema/models/{name}`
* `GET /v3/schema/enums`
* `GET /v3/schema/capabilities`

The MCP server exposes model schemas through `resources/list` and
`resources/read`. Current resources include donor, entity, donation, commitment,
program, household, donor-entity relationship, soft credit, form, field, and
donor-field schemas.

## Scope Planning

Use the smallest key or OAuth grant that still lets the agent do the job.

| Use case | Recommended scopes |
| - | - |
| Donor lookup only | `primitives:donors:search`, `primitives:donors:get` |
| Donor and recipient read-only workflows | `primitives:donors:*`, `primitives:entities:*` |
| Giving summaries | `primitives:donations:list`, `primitives:donations:get`, `primitives:donations:summary` |
| Staff brief with notes and activity | `primitives:dashboard:*`, `primitives:notes:list`, `primitives:activity_logs:list` |
| Saved views and reports | `primitives:filters:list`, `primitives:reports:list` |
| Broad internal admin smoke testing | `primitives:*`, `schema:read` |

Tool discovery only returns operations the current credentials can use. A broad
primitive scope does not bypass Gratona group permissions.


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