Model Context Protocol (MCP) Integration
Relevant source files
The following files were used as context for generating this wiki page:
Model Context Protocol (MCP) integration in Coral provides a unified server interface that connects AI agents to multiple services. Coral acts as a single MCP server, allowing agents to search for operations and execute sandboxed programs that call upstream services using stored credentials and organization policies.
Sources: README.md:3-12, README.md:46-55
Architecture Overview
Coral operates as an intermediary between MCP clients (such as Claude Code or Codex) and upstream service providers. It consolidates multiple MCP servers and OpenAPI-based services into a single access point.
This diagram illustrates the flow from an agent's request through Coral's sandboxed execution and policy gate to final service invocation.
Sources: README.md:46-56
MCP Server Implementation
The Coral MCP server implements standard MCP protocols to manage tasks, tools, and resources. It exposes a specialized toolset that allows agents to discover and interact with the catalog of connected providers.
Internal Core Tools
Coral provides built-in MCP tools that agents use to manage the lifecycle of a request:
| Tool Name | Description | Intent Requirement |
|---|---|---|
start_task | Initializes a unit of user work and lists available namespaces. | What the user asked for. |
search | Queries visible operations and saved functions. | Keywords for capability. |
describe | Retrieves detailed input/output schemas for a specific path. | Schema details needed. |
exec | Executes a sandboxed TypeScript program. | Program logic to run. |
wait | Observes the output and state of a long-running program run. | N/A |
save_function | Saves a successful program as a typed function for future reuse. | When to use the function. |
Sources: crates/coral-mcp/src/arguments.rs:88-164, crates/coral-mcp/src/arguments.rs:200-240
Connection Lifecycle
When a client connects, Coral handles initialization and capability negotiation.
The sequence shows the standard MCP handshake followed by the Coral-specific task initialization.
Sources: crates/coral-mcp/tests/mcp-schema/2026-07-28.json:1150-1200, crates/coral-mcp/src/arguments.rs:88-100
Provider Materialization
Coral "materializes" upstream MCP servers by capturing a discovery snapshot and projecting it into its internal catalog.
Materialization Logic
- Snapshot Capture: Coral pins a normalized MCP discovery snapshot containing server info, capabilities, and tool definitions.
- Schema Transformation: Upstream JSON Schemas are converted into internal schema graphs, ensuring they are faithful to the source while being compatible with Coral's TypeScript projection.
- Path Assignment: Every tool is assigned a stable relative path within the provider's namespace (e.g.,
github.issues.list). - Credential Binding: Coral binds the appropriate authentication contract (Bearer, OAuth, etc.) to the execution binding.
Sources: crates/coral-catalog/src/mcp/materialize.rs:27-100, crates/coral-catalog/src/mcp/materialize.rs:188-210
Effect Hints
Coral honors annotations provided by upstream MCP tools to inform policy decisions.
| Hint | Description | Default Policy |
|---|---|---|
readOnlyHint | Operation does not modify the environment. | enabled |
destructiveHint | Operation may perform destructive updates. | approval_required |
idempotentHint | Repeated calls with same arguments have no additional effect. | N/A |
openWorldHint | Operation interacts with external entities. | N/A |
Sources: crates/coral-catalog/src/mcp/materialize.rs:430-460, crates/coral-grpc/proto/coral/management/v1/provider.proto:60-72
Execution Model
Coral runs agent-provided TypeScript programs in an isolated sandbox. This model reduces context window usage by allowing the agent to perform multiple calls and data processing within a single MCP round trip.
Sandboxed Sandbox
- Isolation: No network access, no imports, and no access to secrets.
- Credential Injection: Coral injects credentials only at the moment an operation is called via the
coral.providersproxy. - Policy Enforcement: Every call made within the program is checked against organization rules (e.g.,
allowed,approval required, ordisabled).
Sources: README.md:16-25, AGENTS.md:45-60
Protocol Metadata
Coral uses MCP _meta fields to pass context between the server and the client, such as progress tokens and client capabilities.
{
"_meta": {
"io.modelcontextprotocol/clientCapabilities": {
"sampling": {},
"roots": {}
},
"io.modelcontextprotocol/protocolVersion": "2025-11-25",
"progressToken": "opaque-token-123"
}
}
Sources: crates/coral-mcp/tests/mcp-schema/2026-07-28.json:1100-1140
Summary
MCP Integration in Coral transforms how agents interact with services by moving from many fragmented servers to a single, governed gateway. By materializing upstream protocols into a typed TypeScript interface and executing logic in a secure sandbox, Coral ensures that agents remain effective while users maintain full control over credentials and data access.