peaka-mcp-server

Query question/sql pairs from Peaka's golden sql vector store. If you find an existing query matching the user's question, just use it. Otherwise use the other tools to figure out the tables and write the query. If you do not already know the projectId for the current task, call peaka_list_projects first and ask the user which project to use. Remember the chosen projectId for subsequent calls in this conversation.

Runs the given sql query on Peaka. BEFORE RUNNING THIS TOOL: 1: Use peaka_get_project_metadata to determine which tables should be used in the query and their schemas. 2: Use peaka_list_tables to determine if the tables of interest are cached or not (this response has isCached property) 3: If one or more tables that you need to query are cacheable but not cached: 3a: Warn the user that the results will be limited and ask if you should start the caching process for those tables, and start the caching process using the create cache tool 3b: If the caching is rejected by the user, warn them that the query results will be limited and use LIMIT statements on the query to make sure it doesn't run forever If you do not already know the projectId for the current task, call peaka_list_projects first and ask the user which project to use. Remember the chosen projectId for subsequent calls in this conversation.

Execute a saved query by its ID in the Peaka project. Use peaka_list_queries to find available query IDs. If you do not already know the projectId for the current task, call peaka_list_projects first and ask the user which project to use. Remember the chosen projectId for subsequent calls in this conversation.

Read a single saved query by its ID. Returns the full query object including displayName, inputQuery (SQL), queryType, and the auto-refresh schedule for materialized queries. If you do not already know the projectId for the current task, call peaka_list_projects first and ask the user which project to use. Remember the chosen projectId for subsequent calls in this conversation.

Create a named, saved query in the Peaka project's semantic layer. Returns the created query object including its ID, which can be passed to peaka_execute_query. If you do not already know the projectId for the current task, call peaka_list_projects first and ask the user which project to use. Remember the chosen projectId for subsequent calls in this conversation.

Update an existing saved query in the Peaka project. Adjusts the display name, SQL body, and/or the auto-refresh schedule (for materialized queries). At least one of displayName, inputQuery, or schedule must be provided. If you do not already know the projectId for the current task, call peaka_list_projects first and ask the user which project to use. Remember the chosen projectId for subsequent calls in this conversation.

Delete a saved query from the Peaka project. Use the queryId returned from peaka_list_queries. If you do not already know the projectId for the current task, call peaka_list_projects first and ask the user which project to use. Remember the chosen projectId for subsequent calls in this conversation.

Trigger a refresh on a materialized saved query in the Peaka project. Use the queryId returned from peaka_list_queries for queries whose queryType is "MATERIALIZED". If you do not already know the projectId for the current task, call peaka_list_projects first and ask the user which project to use. Remember the chosen projectId for subsequent calls in this conversation.

Inspect the auto-refresh state of materialized saved queries in the Peaka project. Returns each query's last refresh status, last/next scheduled execution times, and its schedule settings (interval/cron). Pass a queryId to inspect a single materialized query; omit it to list all of them. If you do not already know the projectId for the current task, call peaka_list_projects first and ask the user which project to use. Remember the chosen projectId for subsequent calls in this conversation.

Get metadata for all catalogs, schemas, and tables in the Peaka project in a single call. Optionally filter by catalogId and/or schemaName. Use this tool to discover the data structure before writing queries. If you do not already know the projectId for the current task, call peaka_list_projects first and ask the user which project to use. Remember the chosen projectId for subsequent calls in this conversation.

Refresh project metadata for a specific catalog. This is a long-running operation that should only be used when a data source has structurally changed (e.g. new tables or columns added). Triggers the refresh asynchronously and returns immediately; it does not wait for completion. Poll peaka_get_metadata_refresh_status to track progress until it reports COMPLETED or FAILED. If you do not already know the projectId for the current task, call peaka_list_projects first and ask the user which project to use. Remember the chosen projectId for subsequent calls in this conversation.

Check the current status of a metadata refresh job for a specific catalog. Possible statuses: NOT_ACTIVE, COMPLETED, WAITING, ACTIVE, DELAYED, FAILED, PAUSED, STUCK. If you do not already know the projectId for the current task, call peaka_list_projects first and ask the user which project to use. Remember the chosen projectId for subsequent calls in this conversation.

Create a cache for a table in the Peaka project. Caching a table improves query performance by storing the data locally. Schedule expressions are optional at creation time and use ISO-8601 durations (e.g. PT6H, P1D, P7D, P30D); they can be set later with peaka_update_cache. If you do not already know the projectId for the current task, call peaka_list_projects first and ask the user which project to use. Remember the chosen projectId for subsequent calls in this conversation.

Create caches for multiple tables in a single call. Use this instead of repeated peaka_create_cache calls when caching many tables — it avoids partial-failure states where some caches are created and others aren't. Each item supports the same optional schedule expressions as peaka_create_cache (ISO-8601 durations, e.g. PT6H, P1D, P7D, P30D). If you do not already know the projectId for the current task, call peaka_list_projects first and ask the user which project to use. Remember the chosen projectId for subsequent calls in this conversation.

Get all cache statuses for tables in the Peaka project. Returns the current caching state, execution history, and progress for each cached table. If you do not already know the projectId for the current task, call peaka_list_projects first and ask the user which project to use. Remember the chosen projectId for subsequent calls in this conversation.

Trigger a full refresh on an existing cache in the Peaka project. Use the cacheId returned from peaka_get_cache_statuses. If you do not already know the projectId for the current task, call peaka_list_projects first and ask the user which project to use. Remember the chosen projectId for subsequent calls in this conversation.

Trigger an incremental update on an existing cache in the Peaka project. Fetches only new/changed rows — much faster than a full refresh. Use the cacheId returned from peaka_get_cache_statuses. If you do not already know the projectId for the current task, call peaka_list_projects first and ask the user which project to use. Remember the chosen projectId for subsequent calls in this conversation.

Update cache settings on an existing cache in the Peaka project. This endpoint replaces — not merges — the schedules, so both incrementalSchedule and fullRefreshSchedule must be supplied with the full intended state every call. Schedule expressions use ISO-8601 durations (e.g. PT6H, P1D, P7D, P30D). If you do not already know the projectId for the current task, call peaka_list_projects first and ask the user which project to use. Remember the chosen projectId for subsequent calls in this conversation.

Delete an existing cache in the Peaka project. Removes the cache entirely; the underlying table is not affected. Use the cacheId returned from peaka_get_cache_statuses. If you do not already know the projectId for the current task, call peaka_list_projects first and ask the user which project to use. Remember the chosen projectId for subsequent calls in this conversation.

List all available catalogs in the Peaka project. Returns catalog names, types, and connection info. If you do not already know the projectId for the current task, call peaka_list_projects first and ask the user which project to use. Remember the chosen projectId for subsequent calls in this conversation.

List all available schemas for a given catalog in the Peaka project. If you do not already know the projectId for the current task, call peaka_list_projects first and ask the user which project to use. Remember the chosen projectId for subsequent calls in this conversation.

List all available tables for a given catalog and schema in the Peaka project. If you do not already know the projectId for the current task, call peaka_list_projects first and ask the user which project to use. Remember the chosen projectId for subsequent calls in this conversation.

List all columns for a given table in the Peaka project. Returns column names, data types, and constraints. Use peaka_get_project_metadata first to discover available catalogs, schemas, and tables. If you do not already know the projectId for the current task, call peaka_list_projects first and ask the user which project to use. Remember the chosen projectId for subsequent calls in this conversation.

List all saved queries in the Peaka project. Returns query names, SQL content, and whether they are plain or materialized. If you do not already know the projectId for the current task, call peaka_list_projects first and ask the user which project to use. Remember the chosen projectId for subsequent calls in this conversation.

List all projects accessible for the user. Use this tool to discover projectIds, then pass the chosen projectId to subsequent tool calls.

Get table relationships (foreign keys) for a catalog in the Peaka project. Useful for understanding how tables connect when constructing JOINs — without this, JOIN conditions have to be guessed from column-name similarity. The response is an open-ended object map keyed by relation identifier. If you do not already know the projectId for the current task, call peaka_list_projects first and ask the user which project to use. Remember the chosen projectId for subsequent calls in this conversation.

Get column-level statistics for a table in the Peaka project. Returns the catalog/schema/table identifiers and a per-column distinctFraction (estimated fraction of distinct values vs total rows), useful for cardinality estimation and query optimization. If you do not already know the projectId for the current task, call peaka_list_projects first and ask the user which project to use. Remember the chosen projectId for subsequent calls in this conversation.

List all data source connections in the Peaka project. Returns each connection's id, name, type, and (for OAuth-based connections) callback URL. Useful for discovering what data sources are wired up; pair with peaka_get_connection_detail for connection-specific configuration. If you do not already know the projectId for the current task, call peaka_list_projects first and ask the user which project to use. Remember the chosen projectId for subsequent calls in this conversation.

Get connection-specific configuration detail for a data source connection in the Peaka project. The response shape varies by connection type — only the `type` field is guaranteed; remaining fields are connection-specific. Use peaka_list_connections to discover the connectionId. If you do not already know the projectId for the current task, call peaka_list_projects first and ask the user which project to use. Remember the chosen projectId for subsequent calls in this conversation.

Create a semantic catalog in the Peaka project. A semantic catalog groups semantic tables — saved queries surfaced as queryable tables — under a single namespace. Returns the created catalog including its id. If you do not already know the projectId for the current task, call peaka_list_projects first and ask the user which project to use. Remember the chosen projectId for subsequent calls in this conversation.

Create a semantic table inside a semantic catalog in the Peaka project. The table is backed by an existing saved query, so the catalog/schema/table identifiers become a queryable view over that query. Use peaka_create_query (or peaka_list_queries) to obtain the queryId, and peaka_create_semantic_catalog (or peaka_list_catalogs) for the catalogId. If you do not already know the projectId for the current task, call peaka_list_projects first and ask the user which project to use. Remember the chosen projectId for subsequent calls in this conversation.

Delete a semantic table from a semantic catalog in the Peaka project. Removes the table mapping only; the saved query that backs it is not affected. If you do not already know the projectId for the current task, call peaka_list_projects first and ask the user which project to use. Remember the chosen projectId for subsequent calls in this conversation.