Coral is a single query interface for agents calling data source APIs.
Agents make fewer, more precise tool calls with Coral than they do with per-source MCP servers, CLI tools, or API wrappers. For agent read tasks, SQL has a structural advantage when a question needs more than one API call: it avoids paginating through large results, returns tabular rows instead of sprawling JSON, brings back only the columns you asked for, and correlates across sources in a single statement.
Everything is local: your data, credentials, and usage history never leave your machine.
Coral ships as a desktop app on macOS, Linux, and Windows. For servers and automation, use the CLI.
Get started
- Install Coral. Use a download above, or see all installation options.
- Add your sources. Connect GitHub, Slack, Datadog, and other bundled sources from the sources page. Coral only fetches data from sources you connect.
- Connect your agents over MCP. The app exposes an MCP server over stdio. Point Claude Code, Codex, Cursor, or VS Code at it — see Use Coral over MCP.
Then ask your agent a question about your data:
Why Coral
Most agent workflows access company data one tool at a time. That works, but it tends to create:
- too many tool calls
- repeated auth, pagination, and retry logic
- poor cross-source reasoning
- high token traffic
- brittle glue code and prompts
Coral gives agents one query interface instead:
- query multiple live sources through SQL
- keep workflows inspectable and scriptable
- expose the same runtime over MCP
- answer cross-source questions without stitching tools together by hand
We benchmarked Coral against direct provider MCPs (Datadog, Sentry, Linear, Slack, and GitHub) for a diverse set of 82 real-world AI tasks using Claude Opus 4.6. Key findings:
-
Widespread impact on performance. Across all tasks, Claude was 20% more accurate and 2x more cost efficient using Coral than using direct provider MCPs. With Coral, Claude also had 42% lower latency.
-
Highest impact on coding agent tasks. Across the more complex tasks that typify coding agent workloads (multi-hop, higher post-processing), Claude was 31% more accurate and 3.4x more cost efficient with Coral.
-
More neutral impact on simpler tasks. For simpler AI tasks, such as raw fact retrieval from knowledge bases, the results were closer, with Claude 6% more accurate and 2% more cost efficient with Coral.
Full benchmark report.
How Coral works
Coral sits between your agents and your data sources: your agents write SQL, and Coral translates it into API calls or file reads, then returns a single result set.
graph LR
Agent["You / your agent"] -->|SQL query| Coral["Coral (local)"]
Coral -->|Result rows| Agent
subgraph Sources["Installed sources"]
GH["github source<br/>(github.* tables)"]
LN["linear source<br/>(linear.* tables)"]
FS["file source<br/>(your_files.* tables)"]
end
Coral --> GH
Coral --> LN
Coral --> FS
subgraph Backing["Backing systems"]
GHAPI["GitHub API"]
LNAPI["Linear API"]
Disk["Local files"]
end
GH -.->|PAT / gh auth token| GHAPI
LN -.->|Personal API key| LNAPI
FS -.->|File path| Disk
Sources. A source spec is a YAML file that declares how to reach an API
or local dataset and which tables and columns it exposes. A source is that
spec plus the credentials and variables you configured for it. When you run
coral source add github, Coral installs the github source and exposes it
at query time as the github SQL schema, so tables like github.issues and
github.pulls become queryable. Start with the
bundled sources or
write your own.
Joins across sources. Because every source appears as SQL tables, you can
JOIN across them in one statement, and Coral executes the join locally
after fetching each side from its backing API or files. For example, to see
which Linear issues are tracking open GitHub pull requests:
SELECT a.issue_identifier, a.url, p.state
FROM linear.attachments a
JOIN github.pulls p ON p.html_url = a.url
WHERE p.owner = 'withcoral' AND p.repo = 'coral'Authentication. On coral source add, Coral reads variables and secrets
from matching environment variables, or prompts for them when you pass
--interactive. These values are stored locally and used only at query time;
credentials never leave your machine.
Built for production. Coral is a read layer by design. For read tasks, SQL outperforms per-source tool calls when complexity outgrows a single API call: Coral handles pagination, returns tabular rows instead of sprawling JSON, and lets the query pick just the columns it needs. Query pushdown and caching keep things responsive and cut unnecessary API traffic.
For a deeper understanding of the internals, see the architecture page.
Sources
Coral bundles popular data sources
— Datadog, GitHub, Linear, Sentry, Slack, Stripe, and more — plus local JSONL
and Parquet files. Run coral source discover to see what your build bundles.
Many more community source specs
live in this repo under sources/community and import
with coral source add --file. Community sources do not appear in
coral source discover, and coral source add <name> installs bundled sources
only.
If neither covers what you need, write your own source spec, or tell us which source to add.
CLI quickstart
This walks the CLI path end to end, from a fresh
install to your
first SQL query. For the desktop app, see Get started above.
If you prefer an interactive wizard, run coral onboard, which guides you
through everything covered below.
1. Install Coral
On macOS:
brew install withcoral/tap/coralOr on Linux:
curl -fsSL https://withcoral.com/install.sh | shOr on Windows 10/11 x86_64, download
coral-x86_64-pc-windows-msvc.zip from the latest GitHub release and put
coral.exe on your PATH.
See all install options.
2. Discover bundled sources
coral source discoverThis lists the bundled sources available in your build.
3. Add a source
For example, add GitHub interactively:
coral source add --interactive githubCoral prompts for any required variables or secrets. For scripted setup, omit
--interactive and provide each input as an environment variable of the same
name, such as GITHUB_TOKEN=ghp_... coral source add github. Once connected,
the source's data is available as SQL tables. To update a source's credentials
later, run the same command again.
4. Query your data
Use coral.tables and coral.table_functions to see available query surfaces:
coral sql "SELECT schema_name, table_name FROM coral.tables ORDER BY 1, 2"
coral sql "SELECT schema_name, function_name FROM coral.table_functions ORDER BY 1, 2"Assuming you've connected GitHub, try listing open issues for a repo:
coral sql "
SELECT number, title, state, created_at
FROM github.issues
WHERE owner = 'withcoral' AND repo = 'coral' AND state = 'open'
ORDER BY created_at DESC
LIMIT 10
"
Next steps
- Search with Coral —
coral searchfinds where to query before you write SQL, across catalog metadata and the values Coral saw while querying your sources - Use Coral over MCP — expose Coral to Claude Code, Cursor, or VS Code over MCP so your agent can query sources directly
- Write a custom source spec — connect any HTTP API or local dataset that isn't bundled yet
- Install Coral skills — teach your coding agent how to use Coral
Use Coral with an agent
Coral ships with a built-in MCP server that presents Coral to your agent as a read-only SQL database. Once you've added at least one source, wire Coral into your agent:
claude mcp add --scope user coral -- coral mcp-stdio # Claude Code
codex mcp add coral -- coral mcp-stdio # CodexFor Cursor, VS Code, Claude Desktop, OpenCode, and manual config examples, see Use Coral over MCP.
Coral also publishes three skills that teach your agent the discovery-first
SQL workflow: coral, coral-create-source-spec, and
coral-review-source-spec.
npx skills add withcoral/skillsOnce connected, ask your agent a question about your data. It should reach for
search first to find the right schemas and tables, fall back to the
coral.tables, coral.table_functions, and coral.columns metadata tables
for catalog discovery, then answer with SQL over the sources you connected.
Local state
Coral stores local state in its platform-specific configuration directory.
You can override the config directory with:
export CORAL_CONFIG_DIR=/path/to/coral-configImportant files include:
config.tomlfor installed-source metadata and non-secret variables- imported source specs under
workspaces/<workspace>/sources/<source>/manifest.yaml - source secrets stored separately within the same local trust boundary
Bundled source specs are not copied into the config directory. Coral resolves them from the current binary when you validate or query a bundled source, so upgrades pick up newer bundled manifests without re-adding the source.
Development
Install the local test runner once with Homebrew:
brew install cargo-nextestOr install it with Cargo:
cargo install cargo-nextest --lockedRun the workspace validation gate from the repository root:
make rust-checksDocumentation
For setup guides, reference docs, and examples, visit withcoral.com/docs.
Community
Questions, ideas, and show-and-tell are welcome in our Discord or on GitHub issues.
Contributing
Contributions are welcome, especially bug fixes, tests, documentation improvements, source improvements, and user-facing usability improvements.
Please read CONTRIBUTING.md before opening a pull
request.
Security
Please do not report security issues in public issues or pull requests. See
SECURITY.md.
Licence
Coral is licensed under the Apache License 2.0. See LICENSE.
