Use Coral over MCP

Coral ships with a built-in MCP server that lets agents discover where data lives across your connected sources, then query it through a read-only SQL interface.

Before setting up a client, create a workspace with coral workspace create <name> — a fresh install has none — and connect at least one source in it.

Client setup

Coral uses stdio transport. If a client supports a command-based install flow, point it at coral mcp-stdio. Create a workspace first — a fresh install has none, and coral mcp-stdio cannot serve one that does not exist:

coral workspace create analytics

Name that workspace with --workspace in the server args of every client below. The examples show one workspace called analytics; substitute your own.

Use add-mcp to add the Coral MCP server to all your favorite coding agents with a single command.

macOS / Linux
Windows PowerShell

npx add-mcp -n coral -g "$(which coral) mcp-stdio --workspace analytics"

npx add-mcp -n coral -g "$((Get-Command coral).Source) mcp-stdio --workspace analytics"

(To install only in the current project, omit the -g flag.)

claude mcp add --scope user coral -- coral mcp-stdio --workspace analytics

CLI

codex mcp add coral -- coral mcp-stdio --workspace analytics

Manual configAdd to ~/.codex/config.toml:

[mcp_servers.coral]
command = "coral"
args = ["mcp-stdio", "--workspace", "analytics"]

Codex uses user-scoped config shared between the CLI and IDE extension, so you only need to configure it once.

CLI

opencode mcp add

OpenCode’s mcp add command is interactive and can add either a local or remote MCP server.Manual configAdd to ~/.config/opencode/opencode.json for global scope, or opencode.json in your project root for project scope:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "coral": {
      "type": "local",
      "command": ["coral", "mcp-stdio", "--workspace", "analytics"],
      "enabled": true
    }
  }
}

OpenCode merges global and project config, with project config taking precedence over global config.

InstallCursor documents one-click install, UI-based setup, and mcp.json configuration. Its CLI reads the same MCP config but does not document a separate add command.Manual configAdd to .cursor/mcp.json for a project-scoped server, or ~/.cursor/mcp.json for a user-scoped server:

{
  "mcpServers": {
    "coral": {
      "type": "stdio",
      "command": "coral",
      "args": ["mcp-stdio", "--workspace", "analytics"]
    }
  }
}

If coral is not on Cursor’s PATH, use the full path from which coral on macOS or Linux, or (Get-Command coral).Source in PowerShell.

InstallUse the Command Palette and run MCP: Add Server, then choose whether to add Coral to the workspace or your user profile.Manual configAdd to .vscode/mcp.json in your workspace:

{
  "servers": {
    "coral": {
      "type": "stdio",
      "command": "coral",
      "args": ["mcp-stdio", "--workspace", "analytics"]
    }
  }
}

For user scope, open the user-profile mcp.json with MCP: Open User Configuration and add the same server entry there.

InstallClaude Desktop now supports local MCP desktop extensions, but Coral currently uses the manual local-server config below.Manual configAdd to claude_desktop_config.json:

{
  "mcpServers": {
    "coral": {
      "command": "coral",
      "args": ["mcp-stdio", "--workspace", "analytics"]
    }
  }
}

Use the full path to coral. Open this file from Claude Desktop → Settings → Developer → Edit Config. Claude Desktop uses user-scoped config for this setup.

Any MCP client that supports stdio transport can use Coral. Point it at:

command: coral
args: ["mcp-stdio", "--workspace", "analytics"]

Consult your client’s documentation for the exact config format.

Verify the connection

Once your client is connected, ask the agent to list available Coral tables or run a small query.

“Use Coral to show what sources and tables you can query.”

“Run a small Coral query against coral.tables.”

If it works, the agent should return installed schemas and tables. You do not need to know the MCP tool names; the agent gets discovery helpers and a read-only SQL interface to the same sources you use from coral sql.

Catalog-qualified table names

The coral://tables resource exposes catalog_name, schema_name, and table_name separately for every table. It also provides name for display and sql_reference for use in FROM and JOIN clauses. Tables with an empty catalog_name use two-part schema.table names. Database tables have a catalog and use three-part catalog.schema.table names. Use the provided sql_reference, which quotes each identifier when required. When calling list_catalog, describe, or list_columns for a database table, pass its catalog separately from its schema; omit the catalog for two-part tables.

What your agent can do

Coral gives your agent a read-only SQL view over the sources you have installed locally. That means your agent can:

inspect the available sources, tables, columns, filters, and table functions
search values Coral observed during earlier queries to find the right table and column
query connected sources without configuring a separate MCP server for each provider
join and aggregate across sources when the question needs more than one API call
use the same local credentials and workspace state as the Coral CLI

Catalog results expose catalog_name, schema_name, and sql_reference separately. Ordinary Coral sources use schema.table; database sources use catalog.schema.table. Pass catalog alongside schema to catalog tools when addressing a database table. Set up and update sources with the CLI. The MCP server is the agent-facing query surface, not a source installer. Only connect Coral to agents you trust. A connected agent can query any source installed in that Coral workspace. See Security for more detail.

How to ask for Coral

When your agent has many tools available, name Coral explicitly:

“Use Coral to find the latest open GitHub issues assigned to me.”

“Use Coral to compare recent deploy errors in Datadog with related Slack messages.”

“Use Coral. Search the catalog for the relevant table or table function, then query the best match.”

“Use Coral to find where payments-api appeared, then query the matching data.”

When the right table or table function is not obvious, ask the agent to search with Coral. The search tool returns catalog metadata and optionally locally observed values. If an answer needs data from multiple connected sources, ask the agent to combine the data in Coral when possible.

Workspaces

Coral has no default workspace and creates none for you. Create one before connecting a client:

coral workspace create analytics

analytics, work, default — they are all ordinary names. Naming a workspace default gives it no special standing and does not make it the one Coral reaches for when a client names none.

Local stdio servers

coral mcp-stdio picks its workspace in this order: the --workspace NAME argument, then CORAL_WORKSPACE in the environment the client launched it with, then your only workspace if you have exactly one. You need to configure a workspace as soon as you have more than one. With two or more and nothing selected, the server refuses to start rather than guessing, and your client reports it as a connection failure. Add --workspace <name> to the server args:

{
  "mcpServers": {
    "coral": {
      "command": "coral",
      "args": ["mcp-stdio", "--workspace", "work"]
    }
  }
}

Pinning the workspace explicitly is worth doing even while you have one — it keeps the client working on the day you create a second.

Loopback MCP over HTTP

coral server can also expose MCP Streamable HTTP on loopback for clients that speak HTTP rather than stdio:

[server.mcp_http]
enabled = true
bind = "127.0.0.1:14556"

Every workspace is served at its own URL; point the client at the one it should work in, for example http://127.0.0.1:14556/mcp/workspace/analytics. No configuration selects a workspace: the URL does, a workspace is reachable as soon as it exists, and creating another workspace later just adds another URL. An unknown name answers not-found until a workspace by that name exists.

Troubleshooting

coral not found: Make sure coral is on your PATH, or use the full path from which coral on macOS or Linux or (Get-Command coral).Source in PowerShell.
The server exits immediately after your client launches it: Run coral workspace list. With no workspaces, create one with coral workspace create <name>. With several and no --workspace in the client’s args, Coral refuses to choose — add the flag naming the one you want.
A stdio server used to start and now does not: Check whether you created another workspace since it last worked. A stdio server needs --workspace from that point on. The HTTP listener is unaffected — each workspace has its own URL.
A workspace URL answers 404: The path must be exactly /mcp/workspace/<name> and the workspace must exist — check the name with coral workspace list. The retired /mcp path no longer serves MCP.
No tables visible: Confirm the client is pointed at the workspace your sources are in, then run coral source list --workspace <name> in your terminal. If empty, add one with coral source add --workspace <name>. See the CLI reference.
The agent ignores Coral: Ask it to use Coral by name. For stronger routing, install the Coral agent skills from Installation.

Get started

Guides

Reference

Project

Client setup

Verify the connection

Catalog-qualified table names

What your agent can do

How to ask for Coral

Workspaces

Local stdio servers

Loopback MCP over HTTP

Troubleshooting

​Client setup

​Verify the connection

​Catalog-qualified table names

​What your agent can do

​How to ask for Coral

​Workspaces

​Local stdio servers

​Loopback MCP over HTTP

​Troubleshooting

Client setup

Verify the connection

Catalog-qualified table names

What your agent can do

How to ask for Coral

Workspaces

Local stdio servers

Loopback MCP over HTTP

Troubleshooting