---
name: sourcey
description: Search and verify startup programs with Sourcey's immutable, provenance-bound registry. Use when an agent needs to discover startup credits, discounts, free tiers, or adoption programs; check structured eligibility; inspect freshness, disputes, evidence, revisions, or change history; consume the Sourcey HTTP API, OpenAPI contract, JSON Feed, or hosted MCP server; or cite an exact Sourcey release without applying for or redeeming an offer.
---

# Sourcey

Use Sourcey as a read-only registry. Treat every answer as a projection of one immutable release,
not as timeless truth.

## Connect

- Website: `https://sourcey.com`
- OpenAPI: `https://api.sourcey.com/openapi.yml`
- API origin: `https://api.sourcey.com`
- MCP manifest: `https://mcp.sourcey.com/mcp.json`
- MCP transport: `https://mcp.sourcey.com/mcp`
- Change feed: `https://api.sourcey.com/feed.json`
- Repository: `https://github.com/sourcey/startup-credits`

Prefer MCP for tool-native discovery and the HTTP API for deterministic integration. Generate a
client from OpenAPI when a typed client is useful; do not depend on an unofficial SDK.

## Preserve the trust boundary

1. Record `release_id` and `artifact_sha256` from every API result.
2. Keep stable IDs and revision digests in stored state; use slugs only for human navigation.
3. Report `provenance.tier`, `freshness`, `dispute`, and `lifecycle` with material claims.
4. Say when eligibility is unknown. Never convert missing criteria into approval.
5. Treat offer value as the structured value in the response, including units and limits.
6. Re-check the current revision before presenting time-sensitive terms.
7. Never claim that Sourcey applied for, redeemed, reserved, or guaranteed an offer.
8. Ask before following a redemption URL or taking an action outside Sourcey.

## Choose a workflow

### Find programs

1. Search offers with `GET /v1/search/offers?q=...` or MCP `search_offers`.
2. Filter results using structured category, lifecycle, value, eligibility, and provenance fields.
3. Read shortlisted offers by stable ID or current slug.
4. Present the exact canonical URL, release ID, revision digest, lifecycle, and evidence state.

Use `GET /v1/search` when the user is looking for vendors rather than individual offers.

### Check eligibility

1. Read the offer first.
2. Collect only criteria represented by the contract: stage, region, funding in USD, company age
   in months, and employee count.
3. Call `GET /v1/eligibility/{entity}/{offer}`, `POST /v1/eligibility/check`, or MCP
   `check_eligibility`.
4. Preserve all three result states:
   - `eligible: true`: supplied facts meet all machine-readable criteria.
   - `eligible: false`: list every entry in `unmet`.
   - `eligible: null`: list every entry in `unknown`; request missing facts if useful.
5. State that the result is a contract evaluation, not vendor approval.

### Verify a claim

1. Read the entity or offer and capture its `revision_digest`.
2. Call `GET /v1/revisions/{id}/provenance` or MCP `get_provenance`.
3. Follow referenced event and observation IDs with `/v1/events/{id}` and
   `/v1/observations/{id}`.
4. Distinguish:
   - `signed`: a current authorized party attested to the revision.
   - `verified`: independent verification satisfies the release policy.
   - `observed`: the release contains bounded source observations without stronger authority.
5. Report stale, unknown, or disputed fields explicitly. Do not summarize them away.

### Follow changes

1. Call `GET /v1/changes` or MCP `get_changes`.
2. Store `next_cursor` exactly as returned.
3. Pass it unchanged on the next call.
4. On `invalid_cursor`, discard it and restart from the retained boundary.
5. Use `https://api.sourcey.com/feed.json` for JSON Feed readers; use `/v1/changes` when exact
   cursor semantics matter.

### Read adoption profiles

1. List an entity's profiles with `GET /v1/entities/{entity}/adoption-profiles`.
2. Read an exact profile with `GET /v1/adoption-profiles/{id}` or MCP
   `get_adoption_profile`.
3. Preserve the profile's basis, grade, lifecycle, revision, and evidence state.
4. Say that no profile is available when the release contains none. Never infer one from brand
   popularity or catalog presence.

## HTTP surface

Use these public version-one operations:

- Status and release: `GET /v1/status`, `GET /v1/release`
- Whole catalog: `GET /v1/catalog`
- Entities: `GET /v1/entities`, `GET /v1/entities/{entity}`,
  `GET /v1/entities/by-slug/{entity}`
- Offers: `GET /v1/offers/{id}`, `GET /v1/offers/{entity}/{offer}`
- Search: `GET /v1/search`, `GET /v1/search/offers`
- Eligibility: `GET /v1/eligibility/{entity}/{offer}`, `POST /v1/eligibility/check`
- Provenance: `GET /v1/provenance/{id}`, `GET /v1/revisions/{id}/provenance`
- Immutable objects: `GET /v1/revisions/{id}`, `GET /v1/events/{id}`,
  `GET /v1/observations/{id}`
- Change stream: `GET /v1/changes`
- Adoption: `GET /v1/entities/{entity}/adoption-profiles`,
  `GET /v1/adoption-profiles/{id}`

Send `Accept: application/json`. Anonymous reads are supported. If the operator supplies a Sourcey
access key, send it as `Authorization: Bearer <token>` for identity and quota only; never expose it
in logs or output.

Read `x-request-id`, `x-sourcey-release-id`, and `x-sourcey-artifact-sha256` from responses when
debugging or preserving evidence. Follow the OpenAPI document for schemas and declared errors.

## MCP surface

Initialize with a supported `MCP-Protocol-Version`, then use:

- `search_offers`
- `get_vendor`
- `get_offer`
- `check_eligibility`
- `get_provenance`
- `get_changes`
- `get_adoption_profile`

Treat `tools/list` as authoritative. The hosted manifest and live tool list must expose the same
tool definitions. All tools are read-only, idempotent, and closed-world. Do not invent write tools
or call hosted account, claim, provider, or maintainer routes through MCP.

## Response discipline

For a recommendation, return:

1. Program and vendor name.
2. Structured value and lifecycle.
3. Eligibility result with unknowns.
4. Provenance tier, freshness, and dispute state.
5. Canonical Sourcey URL.
6. Release ID and revision digest when the result will be stored, cited, or acted on.

Prefer a small evidence-backed shortlist over a long unranked dump. Explain ranking criteria.
Separate registry facts from judgment.

Handle failures as follows:

- `400`: fix the request or restart an invalid cursor.
- `401` or `403`: continue anonymously when the operation permits it; otherwise request a key.
- `404`: report absence in the pinned release; do not infer permanent nonexistence.
- `429`: respect retry metadata and back off.
- `500` or `503`: preserve the request ID and retry safely.

Do not retry malformed requests, authorization failures, or unknown MCP tools unchanged.

## Minimal examples

Search:

```sh
curl -fsS \
  -H 'accept: application/json' \
  'https://api.sourcey.com/v1/search/offers?q=database&limit=20'
```

Check eligibility:

```sh
curl -fsS \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -X POST \
  --data '{"offer_id":"offer_example","stage":"seed","region":"AU"}' \
  'https://api.sourcey.com/v1/eligibility/check'
```

Inspect changes:

```sh
curl -fsS \
  -H 'accept: application/json' \
  'https://api.sourcey.com/v1/changes'
```