Use Coral over MCP - Coral Docs

Coral ships with a built-in MCP server that presents Coral to agents as a read-only SQL database with catalog discovery.

Before setting up a client, make sure you have connected at least one source.

What MCP clients get

Type	Name	Description
Tool	`sql`	Execute read-only SQL against the Coral database
Tool	`list_catalog`	List database tables and table functions with pagination
Tool	`search_catalog`	Search database catalog metadata with a Rust regex
Tool	`describe_table`	Show compact metadata for one database table
Tool	`list_columns`	List columns for one database table with pagination
Resource	`coral://guide`	Database workflow guide for agents
Resource	`coral://tables`	JSON summaries of database tables and required filters

Clients see the same database catalog and query results as coral sql. You set up sources with the CLI, then agents query Coral over MCP as SQL schemas and tables. Agents should treat the discovery tools as catalog helpers, not as replacement provider APIs. For data questions, prefer a single sql call using JOIN, CROSS JOIN, CTEs, subqueries, aggregates, or window functions over multiple tool calls that fetch rows and combine them in the agent.

Discovery tools

list_catalog: paginated list of database tables and parameterized table functions.

Arguments: optional schema, kind, limit, offset. Omit kind (or pass null) to include both "table" and "table_function" items.
For tables, use sql_reference in FROM and JOIN clauses.
For table functions, use sql_call_example and fill in the required arguments.
Do not quote the whole schema.item string: write github.pulls or "github"."pulls", not "github.pulls".

search_catalog: deterministic regex matching over database catalog metadata.

Arguments: required pattern plus optional schema, kind, ignore_case, limit, offset.

describe_table: compact metadata for one table.

Arguments: exact schema and table.
Returns guide text, required filters, and a column count without dumping full columns.

list_columns: paginated columns for one table.

Arguments: exact schema and table, plus optional pattern, ignore_case, required_only, limit, offset.
For existing tables, returns a columns page with total, has_more, and optional next_offset. When pattern is set, matching rows include matched_fields so clients can explain why a column matched.
When the requested table does not exist, returns found: false with recovery hints instead of an empty page. Clients should branch to search_catalog or list_catalog rather than pretending the table has zero columns.

Richer metadata via SQL

For deeper introspection, query coral.tables, coral.columns, coral.filters, coral.table_functions, and coral.inputs through the sql tool instead of relying only on list_catalog or coral://tables. Use coral.filters as the normalized filter surface, with coral.columns.filter_mode available when inspecting filter-only virtual columns.

Searching a provider’s data

Some sources expose native search endpoints (for example, GitHub issue search) as table functions with kind = 'search'. Prefer these over scanning a regular table when the agent needs ranked, query-driven results. They return provider-ranked candidates, so agents should preserve any returned rank columns and use the returned ids plus catalog-described tables to fetch full detail rows when the search result itself is incomplete.

Query result format

The sql tool returns rows as a JSON array of objects. To preserve exact values across JSON parsers, Coral encodes precision-sensitive numeric types as JSON strings rather than JSON numbers:

Int64 (BIGINT) and UInt64
Decimal32, Decimal64, Decimal128, and Decimal256

This applies wherever these types appear, including nested inside Struct, List, and Map columns. The column’s declared SQL type does not change — describe_table, list_columns, and coral.columns still report Int64 or Decimal(p, s); only the JSON encoding of the value is a string. A BIGINT user_id, for example, comes back as { "user_id": "-8504475857937456387" }. Coral does this because MCP uses JSON-RPC, and many clients — JavaScript/TypeScript JSON.parse and most MCP hosts — decode JSON numbers as IEEE-754 doubles. Values beyond 2^53 silently lose precision when read as a number. The CLI is unaffected: coral sql --format json keeps emitting these types as JSON numbers.

Client setup

Coral uses stdio transport. If a client supports a command-based install flow, point it at coral mcp-stdio.

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"

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

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

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

CLI

codex mcp add coral -- coral mcp-stdio

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

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

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"],
      "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"]
    }
  }
}

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"]
    }
  }
}

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"]
    }
  }
}

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"]

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

Verify the connection

Once your client is connected, ask the agent to list available tables or run a simple database query. Examples:

“List the tables available in Coral.”

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

The agent should call list_catalog, search_catalog, or query coral.tables and coral.table_functions to return SQL schemas and catalog items, and use describe_table or list_columns for table-specific metadata. Large catalogs should be paged with limit and offset.

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.
No tables visible: Run coral source list in your terminal to confirm you have sources installed. If empty, add one with coral source add.

​What MCP clients get

​Discovery tools

​Richer metadata via SQL

​Searching a provider’s data

​Query result format

​Client setup

​Verify the connection

​Troubleshooting

What MCP clients get

Discovery tools

Richer metadata via SQL

Searching a provider’s data

Query result format

Client setup

Verify the connection

Troubleshooting