Stack.ai MCP

1. Install the SDK

   Node.js

   npm install @scalekit-sdk/node

   Python

   pip install scalekit

   Full SDK reference: Node.js | Python

2. Set your credentials

   Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

   .env

   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>

3. Authorize and make your first call

   Node.js

   quickstart.ts

   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   
   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENV_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions
   
   const connector = 'stackaimcp'
   const identifier = 'user_123'
   
   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize Stack.ai MCP:', link)
   process.stdout.write('Press Enter after authorizing...')
   await new Promise(r => process.stdin.once('data', r))
   
   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'stackaimcp_audit_logs_list',
     toolInput: {},
   })
   console.log(result)

   Python

   quickstart.py

   import os
   from scalekit.client import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()
   
   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENV_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions
   
   connection_name = "stackaimcp"
   identifier = "user_123"
   
   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize Stack.ai MCP:", link_response.link)
   input("Press Enter after authorizing...")
   
   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="stackaimcp_audit_logs_list",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)

What you can do

Connect this agent connector to let your agent:

• List skills versions, skills, runs — List a Stack AI skill’s full version history, newest first
• Get skills version, skills, run — Fetch one historical version of a Stack AI skill’s full detail: instructions, frontmatter, actions, and file manifest
• Validate skills — Validate a proposed Stack AI skill bundle offline and preview the normalization the write tools would apply
• Update skills — Publish a new version of a Stack AI skill as a full replacement, from text fields or a file bundle
• Rollback skills — Restore a prior version of a Stack AI skill’s content by publishing it as a new latest version
• Create skills, files, project — Create a new Stack AI skill (version 1) from text fields or a file bundle

Tool list

Use the exact tool names from the Tool list below when you call execute_tool. If you’re not sure which name to use, list the tools available for the current user first.

stackaimcp_audit_logs_list#List the active Stack AI organization's audit trail (who did what, when), with optional filters and pagination.10 params▾

List the active Stack AI organization's audit trail (who did what, when), with optional filters and pagination.

NameTypeRequiredDescription

actionstringoptionalFilter by action verb (e.g. "export", "delete", "update", "run").

cursorstringoptionalOpaque pagination cursor from a previous response's pagination.next_cursor.

date_fromstringoptionalISO-8601 lower bound (inclusive) on created_at.

date_tostringoptionalISO-8601 upper bound (inclusive) on created_at.

decisionstringoptionalFilter by decision ("allow" / "deny").

page_sizestringoptionalMaximum entries per page (clamped to 200).

permission_keystringoptionalFilter by permission key (e.g. "org.members.remove").

resource_typestringoptionalFilter by resource type (e.g. "projects").

searchstringoptionalFree-text search across the entry.

user_idstringoptionalFilter to a single acting member's id.

stackaimcp_create_project#Create a new Stack AI project from a natural-language description by generating its nodes and edges with AI assistance.1 param▾

Create a new Stack AI project from a natural-language description by generating its nodes and edges with AI assistance.

NameTypeRequiredDescription

descriptionstringrequiredHigh-level description of what the project should do.

stackaimcp_edit_project#Edit an existing Stack AI project using a natural-language description or a structured patch of node and edge operations.5 params▾

Edit an existing Stack AI project using a natural-language description or a structured patch of node and edge operations.

NameTypeRequiredDescription

project_idstringrequiredNo description.

descriptionstringoptionalNo description.

direct_patchstringoptionalNo description.

dry_runstringoptionalPass true together with ``direct_patch`` to validate the patch without saving. Shows projected node/edge counts and delta; ``published`` is always false for a dry run.

publishstringoptionalNo description.

stackaimcp_files_create_upload_url#Request a presigned PUT URL from Stack AI so the client can upload a large file out of band.5 params▾

Request a presigned PUT URL from Stack AI so the client can upload a large file out of band.

NameTypeRequiredDescription

byte_lengthintegerrequiredExact byte count of the file (1..104857600).

content_hashstringrequiredBase64-encoded SHA-256 of the file's bytes (44 characters, ending in "=").

filenamestringrequiredDisplay name (e.g. invoice.pdf).

mime_typestringoptionalOptional Content-Type hint. Defaults to Stack AI's inference from the filename when omitted.

purposestringoptionalStorage bucket. Defaults to "user-documents".

stackaimcp_files_finalize_upload#Finalize a presigned Stack AI file upload and return a projects_run-ready signed URL.1 param▾

Finalize a presigned Stack AI file upload and return a projects_run-ready signed URL.

NameTypeRequiredDescription

file_idstringrequiredThe file_id returned by files_create_upload_url.

stackaimcp_files_upload#Upload a file inline as base64 to Stack AI and return a signed URL usable in project inputs.4 params▾

Upload a file inline as base64 to Stack AI and return a signed URL usable in project inputs.

NameTypeRequiredDescription

content_base64stringrequiredStandard-alphabet base64 of the bytes.

filenamestringrequiredDisplay name (e.g. invoice.pdf). Used for Content-Disposition and the storage key.

mime_typestringoptionalOptional Content-Type hint. Defaults to application/octet-stream.

purposestringoptionalStorage bucket. Defaults to "user-documents", which is what projects_run doc-* inputs expect.

stackaimcp_get_project#Retrieve a project's node and edge graph as a paginated, self-contained subgraph with connectivity preserved across pages.5 params▾

Retrieve a project's node and edge graph as a paginated, self-contained subgraph with connectivity preserved across pages.

NameTypeRequiredDescription

project_idstringrequiredProject ID (from ``projects_list``).

cursorstringoptionalOpaque pagination token from a prior response's ``pagination.next_cursor``. Pass ``null`` to fetch the first page.

page_sizestringoptionalMaximum nodes per page. Defaults to 50, clamped to [1, 200].

verbosestringoptionalWhen true, also include the raw upstream ``flow`` object verbatim. Off by default to avoid duplicating graph data. Refused with a structured ``flow_too_large`` error (carrying ``next_action`` and node/edge counts) when ``nodes + edges`` exceeds the server's ``max_inline_flow_elements`` cap; in that case page through the flow using ``next_cursor`` instead.

versionstringoptional``"published"`` (default — falls back to draft if none) or ``"draft"`` to read the draft directly.

stackaimcp_get_project_corrections#Re-validate a project draft and return paginated correction entries for params cleaned up during creation or editing.3 params▾

Re-validate a project draft and return paginated correction entries for params cleaned up during creation or editing.

NameTypeRequiredDescription

project_idstringrequiredProject ID to re-validate.

cursorstringoptionalOpaque pagination cursor from a prior response.

page_sizestringoptionalMaximum corrections per page (clamped to 200).

stackaimcp_get_run#Fetch the per-node execution trace for a project run, filtered by severity and optionally expanded with inputs and outputs.7 params▾

Fetch the per-node execution trace for a project run, filtered by severity and optionally expanded with inputs and outputs.

NameTypeRequiredDescription

project_idstringrequiredProject (flow) ID the run belongs to.

run_idstringrequiredRun ID to fetch.

cursorstringoptionalOpaque pagination cursor from a previous response's ``pagination.next_cursor``.

expandstringoptionalOptional list of node ids whose ``inputs`` / ``outputs`` should be populated. Up to 50 ids per call. Ids not in the current page are surfaced in the summary.

page_sizestringoptionalMaximum nodes per page (clamped to 200).

severity_filterstringoptionalWhich nodes to return: ``"failed_or_slow"`` (default), ``"failed"``, ``"slow"``, or ``"all"``.

verbosestringoptionalWhen true, include every node-in-page's inputs/outputs. Use ``expand`` for finer grain.

stackaimcp_list_connections#List the OAuth and API-key connections the authenticated user has configured in Stack AI.3 params▾

List the OAuth and API-key connections the authenticated user has configured in Stack AI.

NameTypeRequiredDescription

cursorstringoptionalOpaque pagination cursor from a previous response's ``pagination.next_cursor``.

page_sizestringoptionalMaximum connections per page (clamped to 200).

provider_idstringoptionalOptional filter, e.g. ``"gmail"``, ``"slack"``. Pass null for all.

stackaimcp_list_knowledge_bases#List knowledge bases available to the authenticated user, with optional verbose metadata.3 params▾

List knowledge bases available to the authenticated user, with optional verbose metadata.

NameTypeRequiredDescription

cursorstringoptionalPagination cursor from a previous response.

page_sizestringoptionalMaximum results per page (clamped to 200).

verbosestringoptionalWhen true, return the full KB metadata for each row instead of the compact projection.

stackaimcp_list_projects#Fetch a paginated list of projects accessible to the authenticated account.3 params▾

Fetch a paginated list of projects accessible to the authenticated account.

NameTypeRequiredDescription

cursorstringoptionalOpaque pagination cursor from a previous response. Pass ``null`` to fetch the first page.

owned_onlystringoptionalWhen true, only return projects the user owns.

page_sizestringoptionalMaximum number of projects per page. Defaults to 50, clamped to [1, 200].

stackaimcp_list_providers_actions#List available Stack AI integration providers and their actions, with optional full schemas for specific action IDs.3 params▾

List available Stack AI integration providers and their actions, with optional full schemas for specific action IDs.

NameTypeRequiredDescription

expandstringoptionaloptional list of action / trigger ids to drill into; only valid with a single ``provider_id`` string.

include_deprecatedstringoptionalWhen true, surface deprecated providers / actions / triggers instead of filtering them. Off by default.

provider_idstringoptional``null``, a single id (e.g. ``"gmail"``), or a list (e.g. ``["gmail", "slack"]``).

stackaimcp_list_triggers#List the cron, polling, and webhook triggers configured on a specific project.2 params▾

List the cron, polling, and webhook triggers configured on a specific project.

NameTypeRequiredDescription

project_idstringrequiredProject (flow) ID to inspect.

verbosestringoptionalWhen true, return the full trigger metadata instead of the compact projection.

stackaimcp_projects_edit_ui#Patch a Stack AI project's UI options (theme, welcome message, allowed origins, etc.) without modifying its flow graph.3 params▾

Patch a Stack AI project's UI options (theme, welcome message, allowed origins, etc.) without modifying its flow graph.

NameTypeRequiredDescription

project_idstringrequiredProject id whose UI options to update.

updatesobjectrequiredObject of UI option fields to merge. At least one key required. Unknown keys raise an error with the list of bad keys.

publishstringoptionalPublish the new draft on success. Defaults to false.

stackaimcp_projects_import#Create a new draft Stack AI project from an exported workflow JSON.3 params▾

Create a new draft Stack AI project from an exported workflow JSON.

NameTypeRequiredDescription

workflow_jsonobjectrequiredParsed export object. Must be JSON-safe. Pass the parsed body, not a string blob.

folder_idstringoptionalOptional folder where the new project should land. Null lets Stack AI pick the default.

project_namestringoptionalOptional name for the new project. When omitted, the name embedded in the export is used.

stackaimcp_projects_validate_flow_json#Run Stack AI's pre-flight validators against a raw flow JSON payload without saving it as a project.4 params▾

Run Stack AI's pre-flight validators against a raw flow JSON payload without saving it as a project.

NameTypeRequiredDescription

flow_jsonobjectrequiredObject with nodes and edges arrays, in the shape returned by projects_get.

cursorstringoptionalOpaque pagination cursor from a prior response.

page_sizestringoptionalMaximum findings per page (clamped to 200).

severity_filterstringoptional"all" (default) or "errors_only".

stackaimcp_run_project#Execute a published Stack AI project by supplying a key-value inputs map that matches the flow's declared input schema.4 params▾

Execute a published Stack AI project by supplying a key-value inputs map that matches the flow's declared input schema.

NameTypeRequiredDescription

inputsobjectrequiredNo description.

project_idstringrequiredNo description.

verbosestringoptionalNo description.

versionstringoptionalNo description.

stackaimcp_runs_list#List a Stack AI project's run history, paginated.3 params▾

List a Stack AI project's run history, paginated.

NameTypeRequiredDescription

project_idstringrequiredProject id whose runs to list.

cursorstringoptionalOpaque pagination cursor from a previous response.

page_sizestringoptionalMaximum rows per page. Defaults to 25, clamped to [1, 200].

stackaimcp_search_kb#Search a Stack AI knowledge base and return the top matching chunks ranked by relevance.5 params▾

Search a Stack AI knowledge base and return the top matching chunks ranked by relevance.

NameTypeRequiredDescription

kb_idstringrequiredKnowledge base ID to search.

querystringrequiredNatural-language search query (must be non-empty).

expandstringoptionalOptional list of ``chunk_id`` values whose full ``text`` should be populated in the response. Other chunks still come back with preview only. Up to 20 ids per call; ids that don't match any chunk in the current result set are surfaced in the summary.

query_strategystringoptionalRetrieval mode: ``"semantic"`` (embedding similarity, default), ``"keyword"`` (BM25), or ``"hybrid"`` (rerank of both).

top_kstringoptionalMaximum chunks to return. Defaults to 5, clamped to [1, 20] (the upstream cap).

stackaimcp_server_info#Return the Stack AI MCP server's version, mode, and capability flags.0 params▾

Return the Stack AI MCP server's version, mode, and capability flags.

stackaimcp_skills_create#Create a new Stack AI skill (version 1) from text fields or a file bundle.5 params▾

Create a new Stack AI skill (version 1) from text fields or a file bundle.

NameTypeRequiredDescription

actionsstringoptionalOptional action refs the skill may invoke, each provider_id.action_id. Pass null for none.

descriptionstringoptionalA one-line description of when to use the skill (text mode only).

filesstringoptionalOptional file bundle (file mode): a list of ``{ path, content_base64 }`` objects with a root ``SKILL.md``.

instructionsstringoptionalThe SKILL.md body, markdown (text mode only).

namestringoptionalThe skill name, unique within the org (text mode only).

stackaimcp_skills_get#Fetch one Stack AI skill's full detail: instructions, frontmatter, actions, and file manifest.1 param▾

Fetch one Stack AI skill's full detail: instructions, frontmatter, actions, and file manifest.

NameTypeRequiredDescription

skill_idstringrequiredThe skill id (from skills_list).

stackaimcp_skills_list#List the Stack AI skills visible to the authenticated user, builtins first.2 params▾

List the Stack AI skills visible to the authenticated user, builtins first.

NameTypeRequiredDescription

cursorstringoptionalOpaque pagination cursor from a previous response's pagination.next_cursor. Pass null to fetch the first page.

page_sizestringoptionalMaximum skills per page. Defaults to 25, clamped to [1, 100].

stackaimcp_skills_rollback#Restore a prior version of a Stack AI skill's content by publishing it as a new latest version.2 params▾

Restore a prior version of a Stack AI skill's content by publishing it as a new latest version.

NameTypeRequiredDescription

skill_idstringrequiredThe skill id to roll back (from skills_list).

versionintegerrequiredThe historical version whose content to restore (1-based, from skills_versions_list). It must not be the current latest version.

stackaimcp_skills_update#Publish a new version of a Stack AI skill as a full replacement, from text fields or a file bundle.6 params▾

Publish a new version of a Stack AI skill as a full replacement, from text fields or a file bundle.

NameTypeRequiredDescription

skill_idstringrequiredThe skill id to update (from skills_list).

actionsstringoptionalThe full replacement list of provider_id.action_id refs. Pass null for none - this clears any existing refs, so re-send the current list to keep them.

descriptionstringoptionalThe full replacement description (text mode only).

filesstringoptionalOptional file bundle (file mode): a list of ``{ path, content_base64 }`` objects with a root ``SKILL.md``.

instructionsstringoptionalThe full replacement SKILL.md body, markdown (text mode only).

namestringoptionalThe skill name (text mode only) - re-send the current one unless you rename it.

stackaimcp_skills_validate#Validate a proposed Stack AI skill bundle offline and preview the normalization the write tools would apply.2 params▾

Validate a proposed Stack AI skill bundle offline and preview the normalization the write tools would apply.

NameTypeRequiredDescription

filesarrayrequiredThe file bundle: a list of ``{ path, content_base64 }`` objects. ``path`` is the relative POSIX path inside the bundle; a root ``SKILL.md`` (exact case) is required.

actionsstringoptionalOptional provider_id.action_id refs to check (format only) and merge into the normalization preview.

stackaimcp_skills_version_get#Fetch one historical version of a Stack AI skill's full detail: instructions, frontmatter, actions, and file manifest.2 params▾

Fetch one historical version of a Stack AI skill's full detail: instructions, frontmatter, actions, and file manifest.

NameTypeRequiredDescription

skill_idstringrequiredThe skill id (from skills_list).

versionintegerrequiredThe version number to fetch (1-based, from skills_versions_list).

stackaimcp_skills_versions_list#List a Stack AI skill's full version history, newest first.1 param▾

List a Stack AI skill's full version history, newest first.

NameTypeRequiredDescription

skill_idstringrequiredThe skill id (from skills_list).

stackaimcp_switch_org#Set the active organization for the current session, routing all subsequent org-scoped tools to that org.1 param▾

Set the active organization for the current session, routing all subsequent org-scoped tools to that org.

NameTypeRequiredDescription

org_idstringrequiredThe Stack AI organization id to activate. Find valid ids by calling ``whoami``.

stackaimcp_validate_workflow#Run pre-flight validation checks on a project draft and return paginated errors and warnings with stable codes and fix hints.4 params▾

Run pre-flight validation checks on a project draft and return paginated errors and warnings with stable codes and fix hints.

NameTypeRequiredDescription

project_idstringrequiredProject ID to validate. The validator always reads the draft, not the published version.

cursorstringoptionalOpaque pagination cursor from a prior response.

page_sizestringoptionalMaximum findings per page (clamped to 200).

severity_filterstringoptional``"all"`` (default) returns errors AND warnings; ``"errors_only"`` drops warnings so an LLM checking "can I run this?" doesn't have to wade through nice-to-haves.

stackaimcp_whoami#Return the authenticated user's profile, active organization, plan, and paginated list of all organizations.2 params▾

Return the authenticated user's profile, active organization, plan, and paginated list of all organizations.

NameTypeRequiredDescription

cursorstringoptionalOpaque pagination cursor from a previous response's ``pagination.next_cursor``. Pass null to start.

page_sizestringoptionalMaximum orgs per page. Defaults to 50, clamped to [1, 200].