Agent Primitives - Gratona Docs

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:

https://api.helpyousponsor.com/mcp

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

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:

Authentication resolves the admin, API key or OAuth token, scopes, and Gratona workspace.
The primitive registry filters discovery and invocation by primitive scope.
Each primitive applies Gratona group permission sets such as donor forms, program access, reports, notes, activity logs, and dashboard permissions.
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:

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.

​Current MCP Tool Surface

​ChatGPT And Codex

​MCP Endpoints

​Auth And Permissions

​REST Primitive API

​Schema Discovery

​Scope Planning