Getting Started Guide
Relevant source files
The following files were used as context for generating this wiki page:
Coral provides a single Model Context Protocol (MCP) server that connects agents to multiple services using your credentials and rules. It runs TypeScript programs written by agents in a sandboxed environment, applies security policies, and records every execution for review.
Sources: README.md:1-10, README.md:32-38
Installation Options
You can deploy Coral as a local desktop application or as a shared server for a team.
Desktop Application
Coral supports macOS, Linux, and Windows.
- Download the installer for your operating system from the releases page.
- Run the installer to set up Coral on your machine.
- Launch the application to access the Coral UI.
Sources: README.md:41-43, apps/desktop/electron-builder.config.ts:86-135
Shared Server
For team use, you must host Coral on a server. This deployment requires explicit authentication configuration.
- Configure a public URL for the Reef interface and the Coral authorization issuer.
- Set the
CORAL_WEB_AUTH_MODEenvironment variable torequired. - Provide a
CORAL_WEB_SESSION_SECRETfor session encryption.
Sources: README.md:41-43, apps/reef/README.md:28-40
Setup and Configuration
The system architecture separates the agent interactions from the administrative interface.
The agent sends programs to the MCP server. The Coral UI allows you to manage providers, set policies, and approve requests.
Sources: README.md:66-78
Core Components
| Component | Description |
|---|---|
| Coral UI (Reef) | The shared human interface for managing workspaces, providers, and approvals. |
| MCP Server | The endpoint agents use to search for operations and execute programs. |
| Sandbox | An isolated environment with no network access or imports where programs run. |
| Provider | A service (e.g., GitHub, Slack) connected to Coral via OpenAPI or MCP. |
Sources: README.md:15-30, apps/reef/README.md:1-5
Development Environment Setup
To contribute to Coral or run it from source, use the automated setup wizard.
Prerequisites
- Node.js (version specified in
apps/reef/.node-version) - Tailscale (recommended for HTTPS and private networking)
- WorkOS account (for hosted authentication development)
Sources: scripts/dev/setup.sh:196-198, apps/reef/README.md:44-55
Setup Steps
- Clone the repository and navigate to the root directory.
- Run the setup script:
./dev setup - Follow the wizard to configure:
- WorkOS environment and Organization IDs.
- OAuth Connect application credentials.
- Tailscale HTTPS mappings (Local ports: Reef
5173, Coral gRPC14555).
- Start the development stack:
./dev run
Sources: scripts/dev/setup.sh:205-256, apps/reef/README.md:10-20
Connecting Your Agent
Each workspace in Coral provides a unique MCP URL.
- Copy the MCP URL from the Coral UI workspace settings.
- Add the URL to your agent's configuration.
- Claude Code:
claude mcp add --scope user --transport http coral <your-mcp-url> - Codex:
codex mcp add coral --url <your-mcp-url>
- Claude Code:
- The agent can now search for available operations and execute tasks.
Sources: README.md:46-56
Summary
Coral centralizes agent access to external services by providing a secure, sandboxed execution environment. By installing the desktop app or hosting a shared server, you maintain control over credentials and policies while allowing agents to execute complex, multi-step TypeScript programs through a single MCP interface.
Sources: README.md:1-30, AGENTS.md:1-10