Coral: a local SQL layer that turns APIs and files into queryable tables for agents

The problem Coral targets: too many tool calls per question

An agent that answers a question by calling provider MCP servers one at a time pays for that structure. The README lists the costs directly: too many tool calls, repeated auth and pagination logic, weak cross-source reasoning, high token traffic, and brittle glue prompts. Each of those is a consequence of the same design choice, which is that the unit of work is a tool call rather than a query.

Coral's argument is that SQL has a structural advantage once a question needs more than one API call. Pagination is handled inside the runtime, results arrive as rows instead of nested JSON, the projection limits the columns returned, and a single statement can correlate two sources. The audience is narrow and specific: teams running coding agents or research agents that read from several company systems and want fewer, more precise calls. It is not a general database and it does not try to be one.

Source specs, SQL schemas, and where the join actually executes

The mechanism rests on a distinction the README draws between a source spec and a source. A source spec is a YAML file declaring how to reach an API or a local dataset and which tables and columns it exposes. A source is that spec plus the credentials and variables 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 github.issues and github.pulls become tables you can select from.

Joins across sources are executed locally. Coral fetches each side from its backing API or files and then joins the two result sets on your machine. That is the detail worth pausing on: the join is not pushed down to either provider, so a cross-source query pays for both fetches before it can produce a row. The README says query pushdown and caching cut unnecessary API traffic, but it does not document how pushdown interacts with a local join, and that is the part an adopter should probe first.

Authentication follows the same local-first line. On coral source add, Coral reads variables and secrets from matching environment variables, or prompts for them when you pass --interactive. The README states that credentials are stored locally and used only at query time and never leave the machine.

Installing the Coral CLI and running a first cross-source query

The README points to the desktop app for macOS, Linux and Windows, and to the CLI for servers and automation. The Makefile shows the CLI install target as a locked cargo install from the workspace path, which means you build from the checked-out repository rather than pulling a published binary.

cargo install --path crates/coral-cli --locked

The workspace pins rust-version to 1.97 and edition 2024, so an older toolchain will refuse the build before anything else happens. Once the binary is on your PATH, add a source. The README gives coral source add github as the example, and notes that credentials are read from matching environment variables or prompted for with --interactive.

coral source add github --interactive

After the source is installed, github.issues and github.pulls are queryable. The README's own cross-source example joins Linear attachments to GitHub pull requests on URL, which is a useful first query because it fails loudly if either source is missing.

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'

Expect rows back, not JSON. If the query returns nothing, check that both sources were added, since the join cannot run against a schema that was never installed.

Read-only by design, and the cases where that is the wrong fit

Coral is a read layer. The README states this plainly, and it is the constraint that decides most adoption questions. If your agent needs to open a pull request, post a Slack message, or mutate a Linear issue, Coral is not the tool for that step, and there is no documented write path to fall back on.

The second limitation is transport. The desktop app exposes an MCP server over stdio, and the README describes pointing Claude Code, Codex, Cursor or VS Code at it. Stdio means the client launches the process; there is no documented remote or HTTP transport, so a hosted agent that cannot spawn a local process is out of scope as described.

The third is source coverage. Coral only fetches data from sources you connect, and a source exists only once a spec is installed. If your system is not among the bundled sources and nobody has written a spec, you are writing YAML before you can write SQL. The README links a guide for custom sources but does not quantify how much work that is. A fourth point: the README does not document rollback for a source add, so plan credential cleanup yourself.

Coral versus per-source MCP servers

The honest comparison is with the thing Coral replaces: one MCP server per provider, each exposing its own tools. The difference is not speed, it is where the logic lives. With provider MCPs, the agent decides how to paginate, which fields to keep, and how to reconcile two systems, and it does that across multiple turns with the full intermediate payload in context. With Coral, that work moves into a SQL statement the runtime executes.

The README reports its own benchmark: 82 real-world AI tasks run with Claude Opus 4.6 against direct provider MCPs for Datadog, Sentry, Linear, Slack and GitHub, with Claude 20 percent more accurate and 2x more cost efficient using Coral overall, 31 percent more accurate and 3.4x more cost efficient on the more complex multi-hop tasks, and 6 percent more accurate and 2x more cost efficient on simple fact retrieval. Those are the project's numbers from its own harness, not an independent result, and the gap narrowing on simple tasks is the most informative part of the report: if your questions are single-endpoint lookups, the provider MCP is already close, and adding a query layer buys you little.

A file-based alternative is a local warehouse such as DuckDB over exported Parquet. That gives you SQL too, but it queries a copy, and Coral's whole point is querying the live source.

Maintenance, licence, and what upgrading costs

The repository is not archived, and the last push was on 2026-09-11. Release cadence is visible in the tags: v0.15.2 on 2026-08-28, v0.15.3 on 2026-09-03, v0.15.4 on 2026-09-04. Versioning is automated through release-please, with the workspace version carrying an x-release-please-version marker, and the release workflow is separate from the validate workflow.

Upgrade cost is mostly the source specs. A spec is YAML that declares tables and columns, and the Makefile exposes lint-sources, fix-sources and schema-check targets, which tells you specs are validated and that a schema change is a deliberate, checked step rather than an incidental one. If you maintain custom specs, budget for re-running those checks on each upgrade. The workspace also pins datafusion, arrow and datafusion-datasource versions, so a dependency bump can move query behaviour between releases.

The licence is Apache-2.0 at the workspace level, which permits commercial use and modification and includes a patent grant. It also means redistributions must carry the licence and notice files and state significant changes. That is a summary of the identifier, not legal advice; read LICENSE and the NOTICE handling before you ship a modified binary.

Editorial conclusion

Adopt Coral if your agents answer read questions that span more than one API and you want the query plan visible as SQL rather than buried in tool-call glue. Skip it if your workflow is writes, streaming, or a single endpoint that one API call already answers. Before committing, verify that a bundled source spec exists for each system you need, that your credentials resolve from environment variables at add time, and that the MCP client you use can launch a stdio server, since the README documents stdio and not a remote transport.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. withcoral/coral on GitHub