Skip to main content
Coral is designed as a local data-access layer for a trusted user and the agents or scripts that user chooses to run. It does not send your source configuration, usage history, or query results to a Coral-hosted service. Source credentials are used locally and sent to the upstream providers you configure when a query requires them.

​
Intended threat model

This release is intended for single-user local use:
  • You install and run the coral binary on your own macOS, Linux, or x86_64 Windows machine.
  • You choose which source specs to install, which credentials to provide, and which MCP clients or scripts may call Coral.
  • Coral stores configuration under the local Coral config directory, which defaults to the platform config directory and can be changed with CORAL_CONFIG_DIR. Source secrets default to OS credential storage when the local keychain is usable, with plaintext file storage available as fallback.
  • CLI and MCP queries run through the same local runtime. The internal gRPC server binds to loopback, and the MCP server uses stdio transport.
Coral reduces data exposure by keeping execution local and by exposing a narrow MCP surface: sql, list_catalog, search_catalog, describe_table, list_columns, optional feedback, coral://guide, and coral://tables. MCP tool and resource metadata can include installed source/schema names so clients can route source-specific requests to Coral during discovery. Secret values are not returned through coral.inputs; secret rows show only whether a value is configured.

​
What Coral protects against

Coral’s current protections are aimed at accidental exposure within that local trust boundary:
  • Source secrets are stored separately from non-secret source variables and are never written into config.toml.
  • By default, sources use the operating-system credential store when Coral can successfully write, read, and delete a probe item. On macOS this uses Keychain; on Windows, Credential Manager; on Linux, Secret Service.
  • If keychain probing fails in auto mode, Coral stores source secrets in plaintext local files and reports the route as file (plaintext) in source output.
  • State files written by Coral use private file permissions on Unix systems. On Windows, Coral stores local state under %APPDATA%\withcoral\coral\config by default and relies on the user’s Windows profile ACLs as the local trust boundary.
  • SQL execution is configured as read-only: DDL, DML, and multiple statements are disabled.
  • Source and workspace names are validated before they are used in local state paths.
  • MCP clients can query installed sources, but they do not receive raw stored secret values through the discovery tables or resources.

​
Secret storage configuration

Coral reads the credential storage preference from config.toml: 
[credentials]
storage = "auto"
Supported values:
ValueBehavior
autoDefault. Use keychain when the probe succeeds; otherwise use plaintext file storage.
keychainRequire OS credential storage. If unavailable, source installation fails.
fileStore source secrets in plaintext secrets.env files under Coral’s config directory.
Changing the global preference does not rewrite existing credentials. To update those, remove and re-add the source you want to update.

​
What you still need to trust

Coral is not a sandbox for untrusted agents, source specs, or credentials. If you give an unsandboxed agent permission to run as your user, that agent may already be able to read local files your OS account can read, such as shell config, project files, or SSH configuration. Coral adds access to the sources you configure; it does not make an otherwise untrusted local agent safe.
  • A connected MCP client can ask Coral to query any source you have installed.
  • A source token can access whatever the upstream provider allows for that token, so prefer read-only and least-privilege credentials.
  • A custom source spec can direct Coral to make HTTP requests or read local file locations declared by that spec. Only install source specs you trust.
  • Anyone who can control your user account should be treated as able to use the configured sources. If a source uses file-backed secret storage, anyone who can read your local Coral config directory should also be treated as able to read its stored source secrets.
  • Coral does not attempt to protect against a compromised machine, compromised MCP client, malicious shell environment, or malicious upstream API response.

​
Practical guidance

  • Scope provider tokens to the minimum data your workflow needs.
  • Put Coral’s config directory on a local disk protected by your operating system account controls.
  • Use coral source list or coral source info <NAME> to inspect whether a source uses keychain or file (plaintext) secret storage.
  • Review custom source specs before installing them, especially base_url, auth, and file location fields.
  • Configure coral mcp-stdio only in MCP clients you are comfortable allowing to query your installed sources.
Report suspected vulnerabilities privately through the project’s security policy.