> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/interface-and-deployment/mcp-reference/stackai-mcp-server.md). # StackAI MCP Server ## Connecting to and Using the StackAI MCP Server The StackAI MCP server connects your AI assistant — Claude, Cursor, or any assistant that supports the [Model Context Protocol](https://modelcontextprotocol.io/) — directly to your StackAI account. Once it's connected, you work by asking. "Which of my workflows failed yesterday?" "Search the HR knowledge base for the parental leave policy." "Build me a workflow that summarizes incoming contracts." The assistant finds the right workflow, reads it, runs it, or fixes it on your behalf, and reports back in plain language. You don't need to learn any commands — there are 32 things it can do on your account, and it picks the right ones for whatever you ask. ## What you can ask for | If you want to… | Try saying | | -------------------------------- | ------------------------------------------------------------------------ | | See what you have | "List my StackAI workflows." · "Which knowledge bases can I access?" | | Understand a workflow | "Walk me through what my Contract Review workflow does." | | Run something | "Run my Invoice Summarizer on this PDF." | | Find out why something broke | "My Lead Enrichment workflow failed this morning — what went wrong?" | | Search your documents | "What does our security knowledge base say about data retention?" | | Build something new | "Build a workflow that reads a support email and drafts a reply." | | Change an existing workflow | "Add a step to my Onboarding workflow that posts a summary to Slack." | | Restyle a chat assistant | "Change the welcome message on my HR Helper and switch it to dark mode." | | Reuse instructions across agents | "Turn this style guide into a StackAI skill I can attach to my agents." | | Check who did what (admins) | "Show me everything this user exported in the last 30 days." | You don't have to phrase things precisely, and you don't need to know which underlying tool does the job. If the assistant needs something from you — a file, a workflow name, permission to publish — it will ask. ## Connect your assistant The connection URL is `https://mcp.stack.ai/mcp`, the same for everyone. There are no API keys to create or paste: the first time your assistant connects, it opens a StackAI sign-in page in your browser. You sign in the way you normally do, approve the connection, and you're done. The connection is tied to your StackAI account and sees exactly what you can see. {% tabs %} {% tab title="Claude.ai" %} Go to **Settings → Integrations → Add More**, paste the URL, and sign in with your StackAI credentials. {% endtab %} {% tab title="Claude Code" %} Run: ```bash claude mcp add --transport http stack-ai-prod https://mcp.stack.ai/mcp ``` {% endtab %} {% tab title="Desktop, Cursor, and other apps" %} Add StackAI as an HTTP connection using the same URL. In apps that use a configuration file, the entry looks like this: ```json {"mcpServers": {"stack-ai-prod": {"type": "http", "url": "https://mcp.stack.ai/mcp"}}} ``` {% endtab %} {% endtabs %} Then start with something that only reads, like *"What StackAI workflows do I have, and which ones are published?"* The assistant will confirm who you are and list them. From there you can point at any one and ask what it does, when it last ran, or why it failed. ## What it can change, and what it can't Most requests only list, read, search, or explain. Building, editing, publishing, uploading, and saving skills change your account. {% hint style="warning" %} **Running a workflow has real-world effects.** A run does exactly what the workflow says to do, which may mean sending an email, posting to Slack, or writing to your CRM. Each run is a real run, so asking twice does the work twice. If you're unsure what a workflow will do, ask the assistant to walk you through it first. {% endhint %} Keep these rules in mind: * **Your permissions still apply.** The assistant only accesses what you can access. * **Read-only deployments block changes.** Build and edit requests return an explicit response. * **Skill history remains available.** Rollbacks create a new version and preserve earlier ones. ## Good to know * **Files:** Upload files up to 100 MB. Use the StackAI web app for larger files. * **Knowledge base search:** Search returns relevant excerpts, not synthesized answers. * **Large workflows:** The assistant may need several passes to read a complete workflow. * **Drafts:** Editing a draft does not update the published workflow until you publish it. * **Imported skills:** Validate them first. Imported bundles are limited to 150 KB. * **Sessions:** Each conversation starts fresh. The assistant looks up account details again. ## Every tool, in plain language You never need to name these — it's a reference so you can see what's in scope. ### Getting started | Tool | What it does | | ------------- | ----------------------------------------------------------------------- | | `whoami` | Confirms who you're signed in as and which organizations you belong to. | | `switch_org` | Moves the conversation to a different organization. | | `server_info` | Reports which features are switched on for your StackAI setup. | ### Finding your work | Tool | What it does | | ----------------------- | --------------------------------------------------------------------------------------------- | | `projects_list` | Lists your workflows, and which of them are published. | | `kb_list` | Lists your knowledge bases, with how many files each one holds. | | `connections_list` | Lists the apps you've already connected, such as Gmail or Slack. | | `catalog_list` | Looks up which apps StackAI can connect to, and what each one can do. | | `project_triggers_list` | Shows what makes a workflow run on its own — a schedule, a webhook, or a check for new items. | ### Looking inside a workflow | Tool | What it does | | ----------------------------- | ------------------------------------------------------------------------------------ | | `projects_get` | Reads a workflow's steps and how they connect to each other. | | `projects_validate` | Checks a workflow for problems and tells you whether it's ready to run. | | `projects_validate_flow_json` | Runs the same checks on a workflow file you haven't saved into StackAI yet. | | `projects_get_corrections` | Lists the settings StackAI corrected or left out when it built or edited a workflow. | ### Runs, troubleshooting, and search | Tool | What it does | | ----------- | ----------------------------------------------------------------------------------- | | `runs_list` | Shows a workflow's run history, including which runs failed and how long each took. | | `runs_get` | Opens a single run to show which step failed and what it was working with. | | `kb_search` | Searches one knowledge base and returns the passages that match best. | ### Reviewing activity (admins) | Tool | What it does | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `audit_logs_list` | Reviews who did what in your organization and when — who edited, exported, or deleted something. For the history of workflow runs, use the run tools above. | ### Skills Skills are reusable instructions you attach to an AI Agent. The first five only read; the last three save changes. | Tool | What it does | | ---------------------- | -------------------------------------------------------------------------------------------- | | `skills_list` | Lists the skills you can attach to an agent. | | `skills_get` | Reads one skill's instructions and files. | | `skills_versions_list` | Shows every version of a skill, newest first. | | `skills_version_get` | Reads one specific earlier version of a skill. | | `skills_validate` | Checks a skill you're importing from another assistant and lists anything that needs fixing. | | `skills_create` | Saves a new skill. | | `skills_update` | Publishes a new version of an existing skill. | | `skills_rollback` | Brings back an earlier version of a skill. | ### Building and running workflows Everything in this group changes your account. | Tool | What it does | | ------------------ | ------------------------------------------------------------------------------------------------- | | `projects_create` | Builds a new workflow from your description and publishes it. | | `projects_import` | Creates a workflow from a workflow file someone exported. | | `projects_edit` | Changes a workflow's steps, and publishes the change if you ask it to. | | `projects_edit_ui` | Changes how a chat assistant looks and behaves — its welcome message, colors, or who can open it. | | `projects_run` | Runs a published workflow and gives you the result. | ### Handing over files These change your account, and the assistant picks the right one for the file's size. | Tool | What it does | | ------------------------- | -------------------------------------------------------------- | | `files_upload` | Uploads a small file so a workflow can use it. | | `files_create_upload_url` | Starts the upload of a larger file. | | `files_finalize_upload` | Finishes a larger file's upload and hands it to your workflow. | ## For developers Full parameter and response detail for every tool is published by the server itself, so it's always current: any MCP client can list the tools and read their complete schemas, and the assistant reads those descriptions before it calls anything. One migration note: every tool was renamed to a `resource_verb` pattern in a recent release — `list_projects` is now `projects_list`, `get_run` is now `runs_get`, and so on. If you have scripts or saved agent instructions that name tools directly, list the tools once and update the names. Conversational use is unaffected. ### Multiple organizations If you belong to several organizations, tell the assistant which workspace to use. It works in one organization at a time. Ask which organization is active if results look unexpected. Workflows and knowledge bases cannot be mixed across organizations in one request. ## Related pages * [MCP Reference](/interface-and-deployment/mcp-reference.md) — overview of StackAI's MCP support * [MCP](/workflow-builder/apps/mcp.md) — connecting workflows to other MCP servers * [Skills](/workflow-builder/utils-logic-and-others/bonus-features/skills.md) — the skills feature these tools manage * [Tools](/workflow-builder/core-nodes/ai-agent-node/tools.md) — tools in the AI Agent node --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.stackai.com/interface-and-deployment/mcp-reference/stackai-mcp-server.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.