Update to ClickHouse

{
  "name": "setup",
  "description": "Guides users through setting up the ClickHouse MCP server connection bundled with this plugin. Use when the user first installs the plugin or has trouble connecting to ClickHouse.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 420
    }
  ],
  "skill_md_contents": "---\nname: setup\ndescription: Guides users through setting up the ClickHouse MCP server connection bundled with this plugin. Use when the user first installs the plugin or has trouble connecting to ClickHouse.\nlicense: Apache-2.0\nmetadata:\n  author: ClickHouse\n---\n\n# ClickHouse Plugin Setup\n\nThis plugin includes the [ClickHouse Cloud Remote MCP server](https://clickhouse.com/docs/use-cases/AI/MCP/remote_mcp) at `https://mcp.clickhouse.cloud/mcp`. It provides secure, read-only access to your ClickHouse Cloud clusters.\n\n## Setup Steps\n\n1. **Install the plugin**: If the plugin is not installed yet, add the marketplace and install the plugin:\n\n   ```bash\n   codex plugin marketplace add ClickHouse/clickhouse-codex-plugin\n   codex plugin add clickhouse@clickhouse-codex-plugin\n   ```\n\n2. **Authenticate the MCP server**: Installing the plugin makes the ClickHouse MCP server available to Codex, but it does not create ClickHouse OAuth credentials. Run:\n\n   ```bash\n   codex mcp login clickhouse\n   ```\n\n   This opens the ClickHouse MCP OAuth flow. Sign in with a ClickHouse account that has access to the organizations, services, databases, and tables you want Codex to inspect. You must also have [MCP enabled on your ClickHouse service](https://clickhouse.com/docs/use-cases/AI/MCP/remote_mcp).\n\n3. **Verify the MCP server is connected**: Check that the ClickHouse MCP server appears in your available MCP servers:\n\n   ```bash\n   codex mcp list\n   ```\n\n4. **Start a fresh Codex thread**: If you installed or authenticated while Codex Desktop was already open, start a new thread so the skills, MCP configuration, and credentials are loaded. If tools still do not appear, restart Codex Desktop.\n\n5. **Test table access**: Ask:\n\n   ```text\n   Using ClickHouse, what tables do I have access to?\n   ```\n\n   or:\n\n   ```text\n   List my ClickHouse databases and tables.\n   ```\n\n## Troubleshooting\n\n- **Server not appearing**: Run `codex mcp list`, then start a new Codex thread so the plugin's skills and MCP configuration are loaded. If it still does not appear, restart Codex Desktop.\n- **Authentication errors**: Re-authenticate with `codex mcp login clickhouse`.\n- **Connection timeouts**: Verify your network can reach `https://mcp.clickhouse.cloud`. The MCP server is a remote HTTP endpoint and requires internet access.\n\n## Keeping queries fast\n\nThe MCP server runs queries against your live ClickHouse Cloud service. To keep interactions responsive and avoid long-running scans:\n\n- Use `LIMIT` clauses to bound result sets.\n- Prefer querying materialized views or pre-aggregated tables over raw scans of large tables.\n- If a query is slow, break it into smaller, faster queries.\n\n## What the MCP Server Provides\n\nOnce connected, the ClickHouse MCP server provides these tools:\n\n### Organization & Service Management\n- **get_organizations** — list all accessible ClickHouse Cloud organizations\n- **get_organization_details** — details of a single organization\n- **get_services_list** — list all services in an organization\n- **get_service_details** — details of a single service\n\n### Database Exploration\n- **list_databases** — list all databases in a service\n- **list_tables** — list tables in a database (supports `like`/`notLike` filtering)\n- **run_select_query** — execute read-only SELECT queries\n\n### ClickPipes\n- **list_clickpipes** — list all ClickPipes for a service\n- **get_clickpipe** — details of a specific ClickPipe\n\n### Backups\n- **list_service_backups** — list all backups for a service\n- **get_service_backup_details** — details of a specific backup\n- **get_service_backup_configuration** — backup schedule and retention settings\n\n### Billing\n- **get_organization_cost** — billing and usage cost data (max 31-day window)\n\nAll tools are read-only. See the [ClickHouse MCP docs](https://clickhouse.com/docs/use-cases/AI/MCP/remote_mcp) for details.\n\n## Bundled Skills\n\nBeyond MCP access, this plugin also bundles ClickHouse skills that activate automatically when relevant — no setup needed:\n\n- **clickhouse-best-practices** — schema design, query optimization, and insert strategy rules\n- **clickhouse-js-node-coding** — writing applications with the ClickHouse JavaScript (Node.js) client\n- **clickhouse-js-node-troubleshooting** — troubleshooting the ClickHouse JavaScript (Node.js) client\n"
}