The MCP Server provides tools that AI agents can use to interact with your data, files, and pipelines in Nekt.
Asking about Nekt
ask_about_nekt
Answers questions about the Nekt platform itself — features, configuration, usage, and capabilities. This tool consults Nekt’s documentation and does not query your data.
Example prompt: “how do I schedule a Query to run every weekday at 6am?”
Querying data
generate_sql
Converts a natural language question into a SQL query based on your table schemas. The generated query is scoped to the tables accessible by the token. You can then execute it using the execute_sql tool.
Example prompt: “write me a query that returns active users in the last 30 days”
get_relevant_tables_ddl
Discovers which tables are relevant to a given question using semantic search. Returns the full schema (CREATE TABLE DDL) for each matched table — useful for understanding available columns and types before generating SQL.
Example prompt: “which tables should I use to analyze customer churn?”
execute_sql
Executes a SQL query against your data warehouse and returns the results as structured data. Supports pagination for large result sets (up to 1,000 rows per page). The SQL dialect adapts automatically to your cloud — BigQuery for GCP and Nekt Express, Athena for AWS.
Example prompt: “run this query and show me the results: SELECT COUNT(*) FROM orders WHERE status = ‘paid‘“
get_table_preview
Returns a small sample (10 rows) from a table to help understand its contents. Useful for inspecting column values, data formats, and categorical fields before writing queries.
Example prompt: “show me a sample of the orders table”
list_tables
Lists tables in the Catalog one page at a time (100 tables per page). Use this when you need a deterministic, complete enumeration of available tables — for example, when browsing the Catalog without a specific question, or when you need a table’s id. For question-driven discovery, prefer get_relevant_tables_ddl.
Example prompt: “list all tables in the trusted layer”
get_semantic_context
Retrieves the most relevant semantic-layer documents for a question using vector search over your business knowledge. Returns curated documentation that explains the business meaning of tables, fields, and metrics, with each document’s referenced warehouse resources already resolved. This is the first step of the query workflow — the context it returns grounds generate_sql in your organization’s own definitions and rules. For semantic context creation, see Adding context.
Example prompt: “explain how we define monthly recurring revenue”
resolve_references
Follows the references inside a semantic-layer document to pull in related tables, fields, measures, or other context documents that weren’t part of the initial match. Use it to traverse the semantic graph when a returned document points to definitions it doesn’t fully contain. Returns the resolved entities along with their names, layers, and descriptions.
Example prompt: “how does the revenue metric connect back to the orders table?”
Browsing files in volumes
list_layers
Lists all data layers (lakehouses) that your token has access to. Returns each layer’s ID, name, slug, and description — use this as the starting point when exploring files stored in Nekt volumes.
Example prompt: “what layers do I have access to?”
list_volumes
Lists volumes (file stores) within a layer, or across all layers if no layer is specified. Returns each volume’s name, slug, and description. Use this after list_layers to discover available file containers.
Example prompt: “what volumes are available in the raw layer?”
list_files
Lists all files stored inside a specific volume. Requires the layer slug and volume slug to scope the results. Returns file metadata including name, type, and size — use this to find the file ID needed to read a file’s content.
Example prompt: “list the files in the contracts volume”
read_file
Downloads and returns the content of a file stored in a Nekt volume. Requires the layer slug, volume slug, and file ID. Returns text files as UTF-8 strings and binary files as base64-encoded content. Files larger than 2 MB cannot be returned inline.
Example prompt: “open the latest invoice in the documents volume and summarize it”
Connecting sources
Sources pull data into Nekt from external systems — Shopify, HubSpot, Postgres, and more. The tools below connect a new source through a draft → publish flow: create a draft, hand the user a secure browser link to complete OAuth or enter secrets (credentials never pass through the chat), validate the live connection, then finalize.
The create flow, step by step:
list_source_connectors / get_source_connector — find the connector and read its config schema to see required and secret fields.create_draft_source — create a draft (the connector slug and a description are required; no tables or pipeline yet).get_source_setup_link — for OAuth/secret connectors, hand the user a deeplink to finish setup in the browser.validate_source_connector_config — test the real connection.check_connector_validation — poll until validation succeeds and the available streams come back.complete_source — finalize the draft: choose streams, output layer, and trigger. Tables are provisioned and the pipeline is deployed.
get_source_connector
Returns a connector’s configuration schema (config_template) — every field, which are required, and which are secret — plus a convenience split so you can decide the flow. Connectors with secret fields (OAuth, API keys, passwords) go through the browser deeplink; connectors without secrets can be configured entirely in chat.
Example prompt: “what do I need to connect Postgres as a source?”
create_draft_source
Creates a draft source — the first step of connecting a source. A draft has no provisioned tables and no deployed pipeline; the connector slug and a description are required, so you can start the connection before any secrets exist. For no-secret connectors, you can pass the full config here directly.
Example prompt: “start connecting our Shopify store as a source”
get_source_setup_link
Mints a time-limited (24h) deeplink for a draft source so the user can complete OAuth or enter secret values in the browser — secrets never pass through the chat. Present the link and wait for the user to finish before validating; the token auto-invalidates once the source leaves draft.
Example prompt: “give me the link to enter the Shopify credentials”
validate_source_connector_config
Tests the connector configuration by actually connecting to the external system, catching bad credentials or wrong hosts before the source is finalized. For drafts set up via the deeplink, it re-validates against the config stored on the backend, so secrets never round-trip through the chat. Returns a validation ID to poll.
Example prompt: “check that the Shopify connection works”
check_connector_validation
Polls a validation job until it finishes. On success, it returns the available streams — the tables/objects the source can pull, each with its supported sync types, fields, primary keys, and replication keys. Present these so the user can choose which streams to sync before completing the source.
Example prompt: “which tables can I pull from this source?”
complete_source
Finalizes a draft source. Requires a description, an output layer, at least one stream, and a trigger (manual, cron, or event). Each stream specifies a destination table name and a sync type — INCREMENTAL (append new/changed rows) or FULL_SYNC (replace all). Completion is one-way: it provisions the warehouse tables and deploys the extraction pipeline.
Example prompt: “pull the orders and customers streams into the raw layer and sync them daily at 6am”
Browsing and managing sources
list_sources
Lists connected sources in your workspace, with filters for free-text search, connector type, status, and archived state. Use it to see what’s already connected or to find a source by name.
Example prompt: “show me all my connected sources”
get_source_details
Returns the full detail of a single source by slug, including its streams and triggers. Configuration values are redacted for security.
Example prompt: “what streams is the Shopify source pulling?”
list_source_connectors
Lists the connector types you can connect as a source, returning each one’s slug and metadata. Use it to discover the slug needed to start a draft.
Example prompt: “what sources can I connect to Nekt?”
update_source_trigger
Changes the trigger of an already-live source — manual, cron (a schedule), or event (run when upstream pipelines finish).
Example prompt: “run the Shopify source every weekday at 7am instead”
update_source_streams
Adds new streams or edits which streams a live source pulls, applied in place without a redeploy. It is non-destructive — it never removes streams or drops tables; to stop a stream, disable it.
Example prompt: “also start pulling the products stream from Shopify”
run_source
Triggers an extraction run of a live source on demand, optionally as a full sync or for selected streams. This consumes credits, so the assistant confirms before running.
Example prompt: “run the Shopify source now”
Connecting destinations
Destinations deliver data out of Nekt to external systems — Slack, Google Sheets, Postgres, webhooks, ad platforms, and more. New destinations are created through a draft → publish flow: create a draft, hand the user a secure browser link to complete OAuth or enter secrets (credentials never pass through the chat), then finalize with the tables to deliver and a trigger. Unlike sources, destinations publish directly — there is no separate validation step.
The create flow, step by step:
list_destination_connectors / get_destination_connector — find the connector and read its config schema to see required and secret fields.create_draft_destination — create a draft (connector slug and a description; tables optional here).get_destination_setup_link — for OAuth/secret connectors, hand the user a deeplink to finish setup in the browser.complete_destination — finalize: choose the tables to deliver and a trigger. The delivery pipeline is deployed.
list_destination_connectors
Lists the connector types you can connect as a destination, returning each one’s slug and metadata. Use it to discover the slug needed to start a draft.
Example prompt: “what destinations can I send data to?”
get_destination_connector
Returns a destination connector’s configuration schema (config_template) — every field, which are required, and which are secret — so you can decide the setup flow. Connectors with secret fields (OAuth, API keys) go through the browser deeplink; connectors without secrets can be configured entirely in chat.
Example prompt: “what do I need to send data to a Postgres destination?”
create_draft_destination
Creates a draft destination — the first step of wiring warehouse tables to an external system. A draft has no deployed delivery pipeline; only the connector slug and a description are required. Input tables are optional here and can be chosen later at completion. For no-secret connectors, you can pass the full config here directly.
Example prompt: “start sending revenue alerts to our #revenue Slack channel”
get_destination_setup_link
Mints a time-limited (24h) deeplink for a draft destination so the user can complete OAuth or enter secret values in the browser — secrets never pass through the chat. The page fills only the connector config, not the tables or trigger.
Example prompt: “give me the link to connect our Slack workspace”
complete_destination
Finalizes a draft destination. Requires the tables to deliver (each with its fields, and optional primary keys or field renames) and a trigger (manual, cron, or event). Destinations publish directly — there is no validation step. Completion is one-way: it deploys the delivery pipeline.
Example prompt: “deliver the daily_revenue table to Slack every weekday at 9am”
Browsing and managing destinations
list_destinations
Lists connected destinations in your workspace, with filters for free-text search, connector type, status, tag, and archived state. Use it to see what’s already connected or to find a destination by name.
Example prompt: “show me all my destinations”
get_destination
Returns the full detail of a single destination by slug. Configuration values are redacted for security.
Example prompt: “what tables is the Slack destination sending?”
run_destination
Triggers a delivery run of a destination on demand. Fire-and-forget — the assistant confirms first, and run history is available through list_pipeline_runs / get_pipeline_run_logs.
Example prompt: “send the revenue report to Slack now”
Creating pipelines
create_query
Deploys a SQL Query as a pipeline in Nekt. Accepts the SQL code, a description, the output layer and table name, and an optional trigger — either a cron schedule or an event trigger that runs the Query when one or more upstream pipelines finish. The pipeline starts in preparing status — poll get_pipeline_status until it leaves preparing, then trigger execution with run_pipeline once the user confirms. Optionally, the Query can be created already connected to a GitHub repo: pass the repository full name (and optionally a branch), and Nekt creates, connects, and pushes the first commit in one step. The folder in the repo is always the generated pipeline slug. See Syncing transformation code to GitHub.
Example prompt: “create a daily Query that aggregates revenue by customer into the trusted layer”
create_notebook
Deploys a Python or PySpark Notebook as a pipeline in Nekt. Accepts the notebook code, a description, the runtime type (python-base, pyspark, or python-browser), optional pip dependencies, and an optional trigger — either a cron schedule or an event trigger that runs the Notebook when one or more upstream pipelines finish. For PySpark notebooks, Spark driver and executor sizing can also be configured. Inputs and outputs are extracted automatically from nekt.load_table and nekt.save_table calls in the code, so the notebook must use the Nekt SDK for all table I/O. Like create_query, the pipeline starts in preparing status and follows the same deploy-then-run lifecycle. It can also be created already connected to a GitHub repo: pass the repository full name (and optionally a branch), and Nekt creates, connects, and pushes the first commit in one step. See Syncing transformation code to GitHub.
Example prompt: “create a PySpark Notebook that joins orders and customers and runs every hour”
manual (runs only on demand), cron (runs on a schedule, with a cron expression and timezone), and event (runs whenever upstream pipelines finish). For event triggers, provide the triggering pipeline slugs and an optional rule — any runs the transformation when any of them completes, all waits for all of them. Use list_pipeline_options to discover the available slugs.
Example prompt: “run the daily_revenue Query whenever the orders and customers sources finish”
list_pipeline_options
Lists all Sources, Queries, Notebooks, and Destinations available as pipeline options, returning each one’s slug, description, and type. Use it to discover the slugs needed to configure an event trigger with update_transformation_trigger, or to get an overview of the pipelines in your organization.
Example prompt: “which pipelines can I use to trigger a transformation?”
create_query / create_notebook), or connect transformations that already exist. Once a transformation is connected, editing its code with update_query / update_notebook auto-commits the change — no extra parameters needed.
list_github_repositories
Lists the repositories the Nekt GitHub App can write to for your organization. Call it once to discover the repo full name (e.g. my-org/analytics) needed when creating or connecting transformations.
Example prompt: “which GitHub repos can Nekt push transformations to?”
Example prompt: “sync my daily_revenue and churn notebooks to the analytics repo”
Running and monitoring pipelines
run_pipeline
Triggers execution of a deployed Query or Notebook pipeline by slug. Returns immediately without waiting for the run to finish — use get_pipeline_status to track progress.
Example prompt: “run the daily_revenue pipeline”
get_pipeline_status
Returns the current status of any pipeline by slug — Queries and Notebooks created through the MCP Server, or Sources and Destinations configured elsewhere in Nekt. Used to track deployment progress after create_query or create_notebook (until status leaves preparing), and to monitor execution after run_pipeline until it reaches a terminal state (success or failed).
Example prompt: “what’s the status of the daily_revenue pipeline?”
list_pipeline_runs
Lists recent runs of any pipeline by slug — Sources, Queries, Notebooks, or Destinations. Returns a summary for each run including its id, status, start and end times, and trigger_type. Supports pagination (up to 100 runs per page). Use this to inspect a pipeline’s execution history, such as checking for recent failures or confirming that a trigger fired.
Example prompt: “show me the last runs of the daily_revenue pipeline”
get_pipeline_run_logs
Fetches the logs of a specific run, or of the most recent run when only a pipeline slug is given. Returns the ERROR-level entries and, when available, Nekt’s AI analysis of the failure — a summary of what happened, the technical details, and a suggested fix. Use this to diagnose a failed run without reading the full log.
Example prompt: “why did the last run of the daily_revenue pipeline fail?”
Adding context
update_resource_description
Updates the Description of a resource in your Catalog. Supported resource_type values are layer, table, field, folder, volume_file, and derived_field. Returns a preview by default — pass confirm=True to apply the change.
When resource_type is derived_field, the tool first identifies the Query or Notebook that produced the target table (via list_queries or list_notebooks), then enriches the field Description with structured tags inferred from the transformation code: @pk, @fk <table>.<column>, @measure additive|non-additive, @attribute, and @grain=<period>. Use this when annotating fact, aggregated, or dimension tables so downstream consumers and AI agents can interpret each column’s role.
Example prompt: “I want to add descriptions to this table: sessions_reviews_consolidated”
create_context_document
Creates a new semantic-layer context document — reusable business knowledge such as metric definitions, segment logic, or table interpretations that should inform future analyses. Documents support annotations (@table, @field, @measure, and more) that link the prose to specific warehouse resources. Returns a preview by default — pass confirm=True to save the document after reviewing it.
Example prompt: “save a definition of net revenue that excludes refunds and chargebacks”
update_context_document
Updates an existing semantic-layer context document when a definition is refined, a segment is added, or business rules change. The full name and content are replaced, so the saved version always reflects the complete document. Returns a preview showing the current versus new content by default — pass confirm=True to apply the change.
Example prompt: “update the revenue definition to also exclude partial refunds”
delete_context_document
Soft-deletes a semantic-layer context document so it no longer influences analyses or appears in semantic search. Use it for obsolete, duplicated, or incorrect knowledge — prefer update_context_document when a document is merely out of date. Returns a preview of the document to be removed by default — pass confirm=True to delete it (there is no undo).
Example prompt: “delete the old churn definition document, it’s outdated”
