Provider Catalog & Recipes
Relevant source files
The following files were used as context for generating this wiki page:
- apps/reef/recipes/schema.json
- apps/reef/app/lib/provider-recipes/recipe-format.ts
- apps/reef/app/lib/provider-recipes/library.server.ts
- apps/reef/app/views/providers/provider-catalog.tsx
- apps/reef/app/lib/provider-recipes/recipes.server.test.ts
- apps/reef/app/views/providers/types.ts
- apps/reef/app/views/providers/configuration-step.tsx
The Provider Catalog & Recipes system enables you to add external services to Coral using pre-configured templates called recipes. These recipes automate the discovery and configuration of OpenAPI documents and Model Context Protocol (MCP) servers, providing a standardized way to manage authentication, server variables, and request headers.
Sources: README.md:31-34, apps/reef/app/lib/provider-recipes/library.server.ts:4-8
Recipe System Architecture
The recipe system uses YAML files stored in the apps/reef/recipes/ directory. Each recipe specifies how Coral should connect to a service, including the source location, authentication methods, and required user inputs.
Component Overview
- Recipe Library: A bundled collection of YAML files and associated assets (icons, OpenAPI documents) processed at build time.
- Provider Catalog: The UI component that groups and displays available recipes to you.
- Configuration Engine: Logic that fills recipe templates using user-provided inputs to generate final provider settings.
Sources: apps/reef/app/lib/provider-recipes/library.server.ts:4-10, apps/reef/app/views/providers/provider-catalog.tsx:109-115
Data Flow
The following diagram illustrates how a recipe is processed from the library to a configured provider:
The system loads recipes eagerly during the server build using Vite's import.meta.glob.
Sources: apps/reef/app/lib/provider-recipes/library.server.ts:12-25, apps/reef/app/views/providers/configuration-step.tsx:162-175
Recipe Format and Schema
Recipes must follow a strict schema defined in recipe-format.ts and enforced by schema.json.
Core Properties
| Property | Type | Description |
|---|---|---|
schema_version | number | Must be 1. |
id | string | Lowercase unique identifier for the recipe. |
display_name | string | Human-readable name for the catalog. |
source | object | Defines either an openapi (URL or file) or mcp (URL) source. |
inputs | object | User-provided values (non-secret) used in templates. |
authentication | object | Supported authentication methods and credential fields. |
Sources: apps/reef/recipes/schema.json:4-100, apps/reef/app/lib/provider-recipes/recipe-format.ts:420-450
Template Syntax
Recipes use a double-brace syntax {{input.name}} to reference values defined in the inputs section. These references are allowed in source URLs, server variables, request headers, and OAuth parameters.
Sources: apps/reef/recipes/schema.json:168-185, apps/reef/app/lib/provider-recipes/recipe-format.ts:85-98
Authentication Methods
Recipes define one or more named authentication options. If multiple options exist, a default property specifies which one to pre-select.
Supported Credential Methods
| Method | Description |
|---|---|
none | No authentication required. |
bearer | Standard HTTP Bearer token. |
header_credentials | Custom credentials sent in named HTTP headers. |
basic_auth | HTTP Basic authentication with username and password fields. |
query_credentials | Credentials added as URL query parameters. |
oauth_authorization_code | Standard OAuth 2.0 flow. |
oauth_discovery | MCP-only flow that finds endpoints via discovery. |
Sources: apps/reef/app/views/providers/types.ts:63-63, apps/reef/app/lib/provider-recipes/recipe-format.ts:241-315
OAuth Configuration
For OAuth flows, recipes can specify:
client: Whether to use a manual client ID or let Coral register one automatically.pkce: Set torequiredordisabled(only for confidential clients).scopes: An array of required permissions.scope_format: How scopes are separated (spaceorcomma).
Sources: apps/reef/recipes/schema.json:547-595, apps/reef/app/lib/provider-recipes/recipe-format.ts:285-300
Catalog and Service Grouping
The ProviderCatalog component organizes recipes by service. Multiple recipes can represent the same service (e.g., an MCP source and an OpenAPI source for GitHub).
Service Logic
The byService helper groups recipes where:
- One recipe has an
idthat matches theserviceproperty of others. - Recipes share the same
serviceidentifier.
Provider Configuration Process
When you select a recipe, the ConfigurationStep component manages the transition from template to provider.
- Input Collection: You enter values for recipe inputs (e.g.,
tenant_idorregion). - Dynamic Refilling: As you change inputs, the engine recalculates dependent fields like URLs or request headers using
filledRecipe. - Server Selection: For OpenAPI sources, you must select or configure servers matching the document's
serversdeclarations. - Submission: The final configuration, including resolved URLs and credential bindings, is posted to Coral to create the provider.
Sources: apps/reef/app/views/providers/configuration-step.tsx:162-200, apps/reef/app/lib/provider-recipes/recipes.server.test.ts:460-500
Validation Rules
The system enforces several constraints to ensure provider security and compatibility:
- No Secrets in Inputs: Inputs are non-secret; credentials must always use the
authenticationfields. - Header Restrictions: Recipes cannot set headers managed by Coral (e.g.,
authorization,content-length,host). - File Access: Bundled OpenAPI documents and icons must reside in the same directory as the
recipe.yamlfile. - URL Safety: URLs must use
httporhttpsprotocols.
Sources: apps/reef/app/lib/provider-recipes/recipe-format.ts:110-135, apps/reef/app/lib/provider-recipes/recipes.server.test.ts:182-200
Conclusion
The Provider Catalog and Recipe system provides a scalable, schema-validated framework for integrating external services into Coral. By combining build-time library bundling with a dynamic configuration engine, it simplifies the complex task of setting up diverse API and MCP providers while maintaining security and consistency.