OpenAPI & External MCP Sources
Relevant source files
The following files were used as context for generating this wiki page:
- crates/coral-catalog/src/mcp/materialize.rs
- crates/coral-catalog/tests/openapi_materialization.rs
- crates/coral-provider/src/input.rs
- crates/coral-grpc/proto/coral/management/v1/provider.proto
- apps/reef/app/lib/provider-recipes/recipe-format.ts
- apps/reef/scripts/gmail-openapi.ts
- crates/coral-provider/src/publication/tests.rs
OpenAPI and Model Context Protocol (MCP) sources provide the operational interface for external services within Coral. Coral acquires these sources from URLs, files, or snapshots and materializes them into a local operation catalog that agents can search and execute.
Sources: crates/coral-provider/src/input.rs:16-25, crates/coral-grpc/proto/coral/management/v1/provider.proto:8-25
Source Acquisition and Setup
The ProviderSetupService manages the lifecycle of adding a new service. Users or programs provide a ProviderSetupSource which the system validates and pins to prevent refetching during publication.
Input Sources
Coral supports the following explicit input sources:
- OpenApiDocument: An exact uploaded OpenAPI JSON or YAML document.
- OpenApiUrl: A document fetched from a specific HTTPS URL.
- McpSnapshot: A normalized discovery snapshot from an MCP server.
- McpUrl: A streamable HTTP MCP server endpoint inspected without credentials.
Sources: crates/coral-provider/src/input.rs:16-29
Setup Lifecycle
The setup process moves through distinct states to ensure configuration and credentials are correct before the provider becomes active.
This state machine represents the sequential steps required to move from raw input to a callable provider.
Sources: crates/coral-grpc/proto/coral/management/v1/provider.proto:246-261
OpenAPI Materialization
Coral materializes OpenAPI documents into a PreparedProviderCatalog. This process involves parsing the document, validating its version, and mapping operations to TypeScript signatures for agent use.
Materialization Logic
- Version Support: Materialization follows the declared OpenAPI version (e.g., 3.0.3 or 3.1.0).
- Schema Handling: Complex schemas are converted into TypeScript declarations. Recursive objects and productive array/map recursion are supported and widened to maintain type safety.
- Constraints: OpenAPI documents are capped at a 32 MiB budget.
- Operation Mapping: Paths and methods become callable operations. Collision paths receive deterministic suffixes to remain unique.
Sources: crates/coral-catalog/tests/openapi_materialization.rs:1145-1155, crates/coral-catalog/tests/openapi_materialization.rs:114-200
Parameter and Response Mapping
| Component | Handling Logic |
|---|---|
| Query Parameters | Fixed queries in path keys become fixed operation parameters. |
| Headers | Reserved headers like Accept or Authorization are omitted from caller arguments. |
| Success Verdicts | Responses are classified as ErrorStatus, Undeclared, Untyped, or Declared. |
| Nullable Fields | OpenAPI 3.0 nullable fields admit null; 3.1 ignores the keyword and relies on type arrays. |
Sources: crates/coral-catalog/tests/openapi_materialization.rs:142-160, crates/coral-catalog/tests/openapi_materialization.rs:1100-1120
MCP Source Materialization
External MCP sources are materialized from discovery snapshots. Coral identifies tools and resources, materializing them into an atomic catalog package.
Protocol and Capabilities
Coral supports MCP protocol versions 2025-06-18 and 2025-11-25. The materializer inspects server capabilities including tools, resources, and task support.
The diagram shows the transformation from a raw MCP snapshot to a prepared catalog.
Sources: crates/coral-catalog/src/mcp/materialize.rs:45-100, crates/coral-catalog/src/mcp/materialize.rs:188-195
Resource and Tool Conversion
- Tools: Every tool is mapped to an
OperationKey. Tools withdestructiveHintorreadOnlyHinthave these flags propagated as operation hints. - Resources: Coral synthesizes a reserved
resources/readoperation for providers that advertise resource capabilities. - Opaque Types: Specific MCP reference types are treated as opaque
McpResourceRefobjects.
Sources: crates/coral-catalog/src/mcp/materialize.rs:105-125, crates/coral-catalog/src/mcp/materialize.rs:328-350
Authentication and Credential Routes
Provider recipes and setups define how Coral authenticates with the upstream service.
Supported Methods
Coral supports several authentication methods for external sources:
- None: No credentials required.
- Bearer: Single opaque token.
- Basic Auth: Username and password pair.
- Header Credentials: Field values sent in named headers (e.g.,
X-API-KEY). - Query Credentials: Credentials passed as URL parameters (OpenAPI only).
- OAuth (Authorization/Device Code): PKCE-protected flows with server-owned polling.
Sources: apps/reef/app/lib/provider-recipes/recipe-format.ts:250-320, crates/coral-grpc/proto/coral/management/v1/provider.proto:265-283
Credential Routes
The CredentialRoute determines how an invocation obtains its identity:
- Fixed: Uses a shared account connected by an owner.
- Caller: Uses the exact account of the invoking principal (user or agent).
- None: No account mapping.
Sources: crates/coral-grpc/proto/coral/management/v1/provider.proto:650-664
Summary
OpenAPI and external MCP sources are the primary integration points for extending Coral's capabilities. The system ensures that these sources are acquired securely, materialized into typed catalogs for agent interaction, and governed by strict authentication policies. Materialization provides a deterministic mapping from upstream definitions to local operations, ensuring agents interact with external services through consistent TypeScript signatures.
Sources: crates/coral-catalog/src/mcp/materialize.rs:35-50, crates/coral-grpc/proto/coral/management/v1/provider.proto:35-55