Jun 23, 2025

How to Use the Stack AI MCP Server

What is Model Context Protocol (MCP)?

Model Context Protocol (MCP) is an open standard that enables AI applications to securely connect with external data sources and tools. Think of it as a bridge that allows AI assistants like Claude to interact with your custom workflows, databases, and APIs in a standardized way.

Instead of being limited to the AI's built‑in capabilities, MCP lets you extend functionality by connecting to:

Custom APIs and workflows
Internal databases
Specialized tools and services
Business‑specific data sources

Why Use Stack AI’s MCP Server?

Stack AI allows you to build powerful AI workflows without code, and with MCP, you can now bring those workflows directly into your favorite AI clients. This means you can:

Access your custom workflows directly from Claude Desktop
Streamline your workflow by eliminating context switching
Scale your AI solutions across different clients and applications

Step‑by‑Step Setup Guide

Prerequisites

Before we begin, make sure you have:

A Stack AI account with a published workflow
Node.js 18+ installed
Git installed

Step 1: Clone the Stack AI MCP Repository

First, let's get the MCP server code on your machine and install dependencies:

git clone <https://github.com/stackai/stack-ai-mcp.git>
cd stack-ai-mcp
npm

Github repo here: https://github.com/stackai/stack-ai-mcp

Step 2: Open Project in Your IDE

Open the stack-ai-mcp folder in your preferred code editor (VS Code, Cursor, etc.).

Step 3: Get Your Stack AI Credentials and Understand Workflow Inputs

Now we need to get your Stack AI API credentials. Here's how:

Publish your Stack AI workflow (if you haven't already)
Go to the Export tab in your Stack AI project
Select "API" from the dropdown menu

You'll see an API URL and Bearer token. Extract the following:

STACK_AI_ORG_ID: The first set of characters in the API URL (before the first /)
STACK_AI_PROJECT_ID: The second set of characters in the API URL (after the first /)
STACK_API_KEY: Click Show Token to reveal the Bearer token value

Understanding Your Stack AI Workflow Inputs

You need to know what inputs your Stack AI workflow expects. In the image above, the example request body on line 13 shows the input structure. Below are two examples

Single input workflow:

{
  "user_id": "user123",
  "in-0": "your input text here"
}

Multiple input workflow:

{
  "user_id": "user123",
  "in-0": "first input",
  "in-1": "second input",
  "in-2": "third input"
}

Step 4: Customize `main.ts` for Your Workflow

Now let's modify the code to match your specific Stack AI workflow. Open src/main.ts in your code editor.

Customizing Tool Discovery (First Function)

Find the ListToolsRequestSchema handler around line 18. This is where you define what Claude sees as available tools.

Single‑input workflow example (like document analysis):

server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [{
      name: "analyze_document",
      description: "Analyze documents for key insights, sentiment, and extract important information like dates, names, and action items",
      inputSchema: {
        type: "object",
        properties: {
          document_text: {
            type: "string",
            description: "The document content to analyze"
          }
        },
        required: ["document_text"]
      }
    }]
  };
});

Multiple‑input workflow example (like content creation):

server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [{
      name: "create_content",
      description: "Generate marketing content including blog posts, social media posts, and email campaigns based on product information and brand guidelines",
      inputSchema: {
        type: "object",
        properties: {
          product_info: {
            type: "string",
            description: "Information about the product or service"
          },
          content_type: {
            type: "string",
            description: "Type of content to create (blog post, social media, email, etc.)"
          },
          target_audience: {
            type: "string",
            description: "Description of the target audience"
          }
        },
        required: ["product_info", "content_type"]
      }
    }]
  };
});

Customizing Tool Execution (Second Function)

Find the CallToolRequestSchema handler around line 37. This is where you process Claude's request and call your Stack AI workflow.

Single‑input workflow example (like document analysis):

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === "analyze_document") {
    const { document_text } = request.params.arguments as { document_text: string };

    const response = await fetch(
      `https://api.stack-ai.com/inference/v0/run/${process.env.STACK_AI_ORG_ID}/${process.env.STACK_AI_PROJECT_ID}`,
      {
        method: "POST",
        headers: {
          Authorization: `Bearer ${process.env.STACK_API_KEY}`,
          "Content-Type": "application/json"
        },
        body: JSON.stringify({
          "in-0": document_text,
          "user_id": "your-user-id-here"
        })
      }
    );

    const result = await response.json();
    return {
      content: [{
        type: "text",
        text: JSON.stringify(result, null, 2)
      }]
    };
  } else {
    throw new Error(`Unknown tool: ${request.params.name}`);
  }
});

Multiple‑input workflow example (like content creation):

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === "create_content") {
    const { product_info, content_type, target_audience } = request.params.arguments as {
      product_info: string;
      content_type: string;
      target_audience?: string;
    };

    const response = await fetch(
      `https://api.stack-ai.com/inference/v0/run/${process.env.STACK_AI_ORG_ID}/${process.env.STACK_AI_PROJECT_ID}`,
      {
        method: "POST",
        headers: {
          Authorization: `Bearer ${process.env.STACK_API_KEY}`,
          "Content-Type": "application/json"
        },
        body: JSON.stringify({
          "in-0": product_info,
          "in-1": content_type,
          "in-2": target_audience || "general audience",
          "user_id": "your-user-id-here"
        })
      }
    );

    const result = await response.json();
    return {
      content: [{
        type: "text",
        text: JSON.stringify(result, null, 2)
      }]
    };
  } else {
    throw new Error(`Unknown tool: ${request.params.name}`);
  }
});

Key Customization Points

Tool Name: Change both instances to match your workflow's purpose.
Description: Write a clear, specific description of what your workflow does. This helps Claude decide when to use it.
Input Schema: Define exactly what parameters Claude should provide. This becomes a contract between Claude and your workflow.
Input Mapping: In the second function, map Claude's parameters to your Stack AI workflow's expected input format (in-0, in-1, etc.).
User ID: Replace the hard‑coded user ID with either a static value or make it dynamic based on your needs.

Step 5: Install Claude Desktop

If you haven't already, download and install Claude Desktop from Anthropic's website.

Step 6: Open Claude Desktop’s Server Config File

Now we need to tell Claude Desktop about our Stack AI MCP server. We'll edit the configuration file:

For macOS:

Open Finder
Press Cmd + Shift + G to open "Go to Folder"
Paste this path: ~/Library/Application Support/Claude/
Open the file claude_desktop_config.json (create it if it doesn't exist)

For Windows:

Navigate to: %APPDATA%\\Claude\\claude_desktop_config.json

Step 7: Add MCP Server Configuration

Add the server details to the contents of claude_desktop_config.json with:

{
  "mcpServers": {
    "stack-ai-workflow": {
      "command": "node",
      "args": ["/absolute/path/to/stack-ai-mcp/src/main.ts"],
      "env": {
        "STACK_AI_ORG_ID": "your_org_id_here",
        "STACK_AI_PROJECT_ID": "your_project_id_here",
        "STACK_API_KEY": "your_api_key_here"
      }
    }
  }
}

Important:

Replace /absolute/path/to/stack-ai-mcp/src/main.ts with the actual path to your cloned repository
Replace the environment variable values with your actual Stack AI credentials from Step 3

Step 8: Test Your Setup

Let's verify everything is working:

Test the MCP server locally by running:
npm
You should see: “Stack AI MCP Server running on stdio”

Restart Claude Desktop to load the new configuration

Step 9: Use Stack AI in Claude Desktop

Open Claude Desktop and start a new conversation. You should now see a tool icon or notice that Claude has access to your custom workflow tool.

Now you can use natural language that matches your workflow's purpose. Claude will automatically understand when to use your tool based on the description you provided. Claude will automatically determine that your question matches the tool's purpose, extract the relevant information, and call your Stack AI workflow (with your permission).

You're All Set! 🎉

Congratulations! You've successfully connected your Stack AI workflows to Claude Desktop using the Model Context Protocol. Now you can:

Run any published Stack AI workflow directly from Claude
Use natural language that matches your workflow's specific purpose
Combine Claude's reasoning with your custom AI workflows
Access your business logic without leaving your conversation

What's Next?

Explore other MCP clients beyond Claude Desktop
Deploy your MCP server and share with your team
Create multiple tools for different workflows in the same server
Contribute to the Stack AI MCP repository on GitHub

Pro Tips for Better Integration

1. Write Descriptive Tool Names

Instead of generic names like run_workflow, use specific names like analyze_financial_data or generate_marketing_copy. This helps Claude understand when to use each tool.

2. Provide Clear Input Descriptions

The more specific your input descriptions, the better Claude will be at extracting the right information from user questions. Instead of “The input for the workflow”, write “The financial data or question to analyze (e.g., 'Q3 revenue breakdown' or 'profit margin trends')”.