Skip to main content
The MCP Server provides tools that AI agents can use to interact with your data, files, and pipelines in Nekt. Most tools appear in your agent’s tool list the moment it connects. A handful of rarely-used ones are kept off that list and reached through a dispatcher (get_tool_details → run_tool), and Live Data tools are always reached through a dispatcher (discover_live_tools → run_live_tool). Both are explained below — the tools themselves are fully available either way.
Have skills, automations, or saved prompts that call Nekt tools by name? Several tools were merged into generic versions that take a kind argument, and the old names no longer exist. See Changed tool names at the bottom of this page.

​
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

The path is: read the business context, find the right tables, generate SQL, run it.

​
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. It is also what decides whether a question should be answered from the warehouse or from a Live Data connection. For creating semantic context, see Adding context.
Example prompt: “explain how we define monthly recurring revenue”

​
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?”

​
generate_sql

Converts a natural language question into a SQL query based on your table schemas and the business context retrieved above. 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”

​
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. When a query fails, the error comes back with a likely explanation rather than the raw engine text alone — in particular it distinguishes a table that exists in your Catalog but has not been materialized yet (the pipeline that writes it hasn’t produced data) from a table name that is simply wrong, so your agent stops guessing at names that were already correct.
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”

​
Browsing what’s connected

Two tools cover everything in your workspace — sources, destinations, Queries, and Notebooks. Both take a kind argument.

​
list_resources

The single browse tool over all resource types. kind accepts: Supports free-text search, plus status, tag, connector_slug, and output_table_name filters and pagination (100 per page). Pass include_trigger=True to also project each row’s current trigger — that’s how you review existing schedules, and how your agent discovers the pipeline slugs available to an event trigger. For transformations, each row also carries the GitHub repo the code is mirrored to, if any.
Example prompt: “show me all my connected sources”

​
get_resource

Returns the full detail of a single source or destination by slug — including its streams and triggers for a source. Configuration values are redacted for security. For a transformation’s code, use get_code instead.
Example prompt: “what streams is the Shopify source pulling?”

​
Connecting sources

Sources pull data into Nekt from external systems — Shopify, HubSpot, Postgres, and more. New sources 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), validate the live connection, then finalize. Every step is a cross-kind tool called with kind="source":
  1. list_connectors(kind="source") / get_connector(kind="source") — find the connector and read its config schema to see required and secret fields.
  2. create_draft(kind="source") — create a draft (connector slug and a description are required; no tables or pipeline yet).
  3. get_setup_link(kind="source") — for OAuth/secret connectors, hand the user a deeplink to finish setup in the browser.
  4. validate_source_connector_config — test the real connection.
  5. check_connector_validation — poll until validation succeeds and the available streams come back.
  6. complete_pipeline(kind="source") — finalize the draft: choose streams, output layer, and trigger. Tables are provisioned and the pipeline is deployed.
Connectors with no secret fields can skip step 3 — pass the full config directly at create_draft.

​
list_connectors

Lists the connector types you can connect, returning each one’s slug and metadata. Use it to discover the slug needed to start a draft. Pass kind="source" or kind="destination".
Example prompt: “what sources can I connect to Nekt?”

​
get_connector

Returns a connector’s configuration schema (config_template) — every field, which are required, and which are secret — plus a convenience split so your agent 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. Pass kind="source" or kind="destination".
Example prompt: “what do I need to connect Postgres as a source?”

​
create_draft

Creates a draft source or destination — the first step of connecting one. 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”
Mints a time-limited (24h) deeplink for a draft 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 continuing; the token auto-invalidates once the resource leaves draft. The page fills only the connector config, not streams, tables, or triggers.
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. This step is source-only — destinations publish directly.
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_pipeline

Finalizes a draft. For a source (kind="source"), it 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). For a destination (kind="destination"), it takes the tables to deliver and a trigger. Completion is one-way: it provisions warehouse tables and deploys the pipeline.
Example prompt: “pull the orders and customers streams into the raw layer and sync them daily at 6am”

​
Managing a live source

Once a source is published, these change it in place.

​
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. Removing streams and dropping tables is deliberately left to the web app.
Example prompt: “also start pulling the products stream from Shopify”

​
update_trigger

Changes the trigger of an already-live source — manual, cron (a schedule), or event (run when upstream pipelines finish). Use kind="source". The same tool handles transformation triggers; see Creating and editing pipelines.
Example prompt: “run the Shopify source every weekday at 7am instead”

​
run_pipeline

Triggers an extraction run of a live source on demand, optionally as a full sync or for selected streams. Use kind="source". 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. The flow is the same shape as a source, with kind="destination", and one difference: destinations have no validation step — they publish directly.
  1. list_connectors(kind="destination") / get_connector(kind="destination") — find the connector and read its config schema.
  2. create_draft(kind="destination") — create a draft (connector slug and a description; input tables optional here).
  3. get_setup_link(kind="destination") — for OAuth/secret connectors, hand the user a deeplink to finish setup in the browser.
  4. complete_pipeline(kind="destination") — finalize: choose the tables to deliver (each with its fields, and optional primary keys or field renames) and a trigger. The delivery pipeline is deployed.
Browsing destinations is list_resources(kind="destination") and get_resource(kind="destination"); running one on demand is run_pipeline(kind="destination") — fire-and-forget, with the assistant confirming first. Run history comes from list_pipeline_runs and get_pipeline_run_logs.
Example prompt: “start sending revenue alerts to our #revenue Slack channel”

​
Creating and editing 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. It is two-phase: the first call returns an authoring guide and a preview of exactly what will be created, without creating anything; your agent shows you that and only creates the pipeline on a second call with confirm=True. The pipeline then starts in preparing status — poll get_pipeline_status until it leaves preparing, then trigger execution with run_pipeline once you confirm. 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. 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, it is two-phase (preview first, then confirm=True), follows the same deploy-then-run lifecycle, and can be created already connected to a GitHub repo.
Example prompt: “create a PySpark Notebook that joins orders and customers and runs every hour”

​
get_code

Returns the current code of a Query or Notebook by slug, along with its configuration and whether it is connected to a GitHub repo. Use it before editing so changes are made against what is actually deployed.
Example prompt: “show me the code of the daily_revenue Query”

​
update_transformation

Edits an existing transformation — a Query or a Notebook, with no kind argument; it infers the type. Updates the code, description, dependencies (Notebooks only), active state, and retry settings. If the transformation is connected to GitHub, changing its code auto-commits the change; no extra parameters are needed.
Example prompt: “update the daily_revenue Query to also exclude refunded orders”

​
update_trigger

Replaces the trigger of an existing pipeline. Supports three trigger types: 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 it when any of them completes, all waits for all of them. Use list_resources(kind=..., include_trigger=True) to discover the available slugs. Defaults to kind="transformation"; pass kind="source" for a source.
Example prompt: “run the daily_revenue Query whenever the orders and customers sources finish”

​
Running and monitoring pipelines

​
run_pipeline

Triggers execution of a deployed pipeline by slug. Defaults to kind="transformation" (Queries and Notebooks); pass kind="source" to trigger an extraction or kind="destination" to trigger a delivery. 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 — Sources, Queries, Notebooks, or Destinations. 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. Returns a summary for each run including its id, status, start and end times, and trigger_type. Paginated (25 per page by default, up to 100). 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

The semantic layer is the curated business knowledge your agent reads before writing SQL — what tables and fields mean, how metrics are defined, and which source to prefer for which question. get_semantic_context (above) reads it; these tools curate it.

​
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_resources(kind="transformation")), 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, @layer, @measure, @transformation, @source, @destination, @context) that link the prose to specific warehouse resources. Returns a preview by default — pass confirm=True to save the document after reviewing it. Context documents are also how you steer Live Data routing: a document that says which questions should be answered from a connected app rather than the warehouse makes that routing automatic next time.
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

Reached through the dispatcher — see More tools.
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”

​
resolve_references

Reached through the dispatcher — see More tools.
Follows the annotations 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?”

​
Live Data

Live Data tools read from and write to your connected apps in real time — HubSpot, Slack, Grafana, an ad platform — rather than reading the copy of that data in your warehouse. Because the set of live tools grows with every connector you attach, they are not listed individually in your agent’s tool list. Two tools cover all of them.

​
discover_live_tools

Lists your organization’s connected Live Data tools, grouped by connection — the connector, its namespace, and for each tool its exact name, description, input schema, and whether it writes. It refreshes on demand, so a connector you linked after your client connected shows up without reconnecting.
Example prompt: “what live tools do I have connected?”

​
run_live_tool

Calls a live tool by name, passing arguments built from its input schema. Since live tools aren’t listed individually, this is how every one of them is invoked.
Example prompt: “create a HubSpot deal for Acme Corp at $12,000”
The call order is:
Why discovery comes first. Live tool names are specific to your organization and can change, so an agent should resolve them at run time rather than hardcoding them into a skill or automation. Discovery also disambiguates two connections of the same app — a Marketing HubSpot and a CS HubSpot show up as separate entries, so your agent can ask which one you mean.
Live Data connections are visible only to full-access tokens. A limited or table-scoped token will not see them. If your organization has no Live Data connections, these tools simply return nothing and the routing guidance is omitted from your agent’s tool list entirely.
Write tools are enabled one by one per connection, and your agent confirms before calling one. After routing a question to a live tool, your agent will typically offer to save a context document recording that routing, so the next similar question goes to the right place automatically.

​
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?”
The remaining three file tools are reached through the dispatcher — see More tools.

​
list_volumes

Reached through the dispatcher — see More tools.
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

Reached through the dispatcher — see More tools.
Lists files stored inside a specific volume, one page at a time (100 per page). 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

Reached through the dispatcher — see More tools.
Downloads and returns the content of a file stored in a Nekt volume. Requires the layer slug, volume slug, and file ID. Text files (md, txt, csv, json, yaml, xml) come back as UTF-8 strings and PDFs as extracted text, so the agent can answer from the content directly; other binaries come back as base64. Maximum inline size is 2 MB. When you want the original file rather than its content — to forward, attach, or save it — the download parameter returns a presigned URL, a base64 string, or an MCP resource blob instead (up to 10 MB).
Example prompt: “open the latest invoice in the documents volume and summarize it”

​
Syncing transformation code to GitHub

Query and Notebook code can be mirrored into your own GitHub repository (one GitHub App installation per organization). The repo is a code mirror — a transformation’s trigger, output layer, and settings still live in Nekt. There are two paths: create a transformation already connected to a repo (via create_query / create_notebook), or connect transformations that already exist. Once a transformation is connected, editing its code with update_transformation auto-commits the change — no extra parameters needed. To see which transformations are already connected and where, use list_resources(kind="transformation") — each row carries its GitHub repo.

​
list_github_repositories

Reached through the dispatcher — see More tools.
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?”

​
connect_transformations_to_github

Reached through the dispatcher — see More tools.
Connects one or more existing Queries or Notebooks to a GitHub repo, uploading each one’s current code as a commit. This is the only way to connect a transformation that already exists — there is no GitHub parameter on the update tool. Connecting overwrites any existing repo binding, so your agent warns before re-pointing a transformation that’s already connected elsewhere.
Example prompt: “sync my daily_revenue and churn notebooks to the analytics repo”

​
More tools

A long tool list measurably degrades how accurately an agent picks the right tool, so seven rarely-used tools are kept off the main list. They remain fully available through two dispatcher tools, and they are documented in their own sections above.

​
get_tool_details

With no argument, returns a catalog of every tool kept off the main list. With a tool name, returns that tool’s full documentation and input schema, plus whether it writes or is destructive — so your agent can confirm with you before firing a write.

​
run_tool

Runs one of those tools by name, passing the arguments built from its schema. Two-phase tools behave exactly as documented — call again with confirm: true in the arguments to commit. The tools reached this way:
Once your session uses one of these, it becomes directly callable for the rest of that session — you only pay the extra discovery step the first time.

​
Changed tool names

Several tools were merged into generic versions that take a kind argument. The old names no longer exist. If you have saved skills, automations, or prompts that call them, update them using this table — the arguments are otherwise unchanged.
list_pipeline_options is the one tool that was removed rather than renamed. It returned every pipeline in a single unpaginated response; list_resources is paginated and filtered by kind, so an automation that relied on getting everything at once needs its logic adjusted, not just its name swapped.
Ask your agent to do the migration for you — point it at your skill or automation files and give it this table. It can find and update every reference in one pass.