# Clidelity agent integration guide

Clidelity is an AI sales system for women coaches and consultants. This page is for agents and developers connecting to it programmatically. The product name is Clidelity, the domain is clidelity.com, and the operator is KHUD Branding Studio (K. Hud Coaching LLC).

## What you can do

The agent surface is a Model Context Protocol (MCP) server. It is read-only. Every result is scoped to the single coach who authorized the connection. There is no cross-tenant read and no write tool.

| Tool | What it returns |
|---|---|
| `list_prospects` | The coach's pipeline. Filter by stage (prospects, active_clients, past_clients, all), search by name or email, limit up to 100. |
| `get_prospect` | One client record. Pass `include_closing_strategy: true` to include the closing strategy and kickoff plan Clidelity generated for that client. |
| `list_tasks` | The coach's open or completed follow-up tasks, optionally filtered to one client. |

## Endpoint

- MCP endpoint: `https://clidelity.com/mcp` (streamable HTTP, any method, OAuth bearer auth)
- MCP server manifest: `https://clidelity.com/.well-known/mcp.json`
- OpenAPI specification for the public HTTP endpoints: `https://clidelity.com/openapi.json`. Those endpoints serve the product's own pages. Prefer the MCP tools for workspace reads.
- The `initialize` handshake and the `initialized` notification are answered without auth, so a client can complete protocol discovery before running OAuth. Every other request without a token returns 401 with a `WWW-Authenticate` header carrying `resource_metadata`, which points at the protected resource document below. Follow that chain rather than hardcoding endpoints.

## Auth

Authorization is OAuth 2.0. Clidelity is the protected resource. The authorization server is the Supabase auth server for the Clidelity project.

1. Fetch `https://clidelity.com/.well-known/oauth-protected-resource` (RFC 9728). It names the authorization server and the supported scopes.
2. Fetch `https://clidelity.com/.well-known/oauth-authorization-server` (RFC 8414). It relays the authorization server's own metadata, including the authorization, token, and registration endpoints and `scopes_supported`. The `issuer` field in that document is the authorization server's canonical URL. Use the endpoints it declares.
3. Run the standard authorization code flow with PKCE. The signed-in coach approves the connection on a consent page inside Clidelity.
4. Call the MCP endpoint with `Authorization: Bearer <access_token>`.

Tokens act as the coach who approved them. Request the smallest scope set the metadata offers. A token from a different Supabase project or audience is rejected.

## Getting an account

Access requires a Clidelity coach account. Signup is invite-gated while the founding cohort of 20 onboards. There is no self-serve API key and no sandbox tenant today. If you are building on behalf of a coach who already has an account, the OAuth flow above is self-serve end to end. For anything else, write to hello@khudco.com with the word agent in the subject line.

## Versioning and deprecation

The public HTTP API is versioned by date. Every `/api/public/*` response carries the current version in the `Clidelity-Api-Version` header. A client may pin by sending the same header on the request. A supported pin is honored, an unknown pin answers 400 naming the supported versions, and omitting the header means the current version.

Breaking changes ship under a new version date. A deprecated version or operation keeps working for at least 90 days after its replacement ships, is marked deprecated in the OpenAPI document, and signals retirement in responses with the `Deprecation` header plus an RFC 8594 `Sunset` header carrying the retirement date. Nothing is deprecated today, so neither header appears yet.

## Rate limits

Every `/api/public/*` response carries the IETF draft `RateLimit` and `RateLimit-Policy` header fields, with the legacy `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` names alongside for older clients. Limits are per IP on a fixed one-hour window, and each operation's budget is stated in its OpenAPI description. A 429 carries `Retry-After` in seconds. Self-throttle on `RateLimit-Remaining` rather than driving into the 429.

## Behavior notes for crawlers and agents

- Nonexistent paths return a real HTTP 404 with links to the sitemap and this guide. A 200 means the page exists.
- `https://clidelity.com/llms.txt` is the index of everything on this page.
- `https://clidelity.com/sitemap.xml` lists the indexable pages. App routes behind sign-in carry a noindex meta tag.
- Public API routes under `/api/` are for the product's own intake and screening pages. They are rate limited per IP and are not a general-purpose API. Use the MCP server instead.

## Contact

Questions, scope requests, or integration problems: hello@khudco.com. Product information: https://clidelity.com/about.