# StackAI MCP Server

                                                                                                                                                                                                                                                                                                                                                                               The Stack AI MCP Server lets AI assistants (e.g. Claude) to manage and interact with your Stack AI projects directly. 

### Supported Actions

The server exposes four actions that an AI assistant can call on your behalf.

<table><thead><tr><th width="173.0703125">Action</th><th width="564.171875">Description</th></tr></thead><tbody><tr><td><code>whoami</code></td><td>Confirms the connected account by returning the user email</td></tr><tr><td><code>list_projects</code></td><td>Returns all your projects and their available workflows</td></tr><tr><td><code>run_workflow</code></td><td>Executes a published workflow</td></tr><tr><td><code>create_workflow</code></td><td>Builds a new workflow from a natural language description</td></tr></tbody></table>

### Connect an MCP Client

The Stack AI MCP Server uses OAuth for authentication. The first time you connect, your MCP client will open a browser window for you to sign in with your Stack AI credentials. After that, your client handles the token automatically.&#x20;

To connect to the StackAI MCP server, there are three options available. &#x20;

#### Option 1: Stack AI Hosted Server

If you're using Stack AI's hosted MCP server, the server URL is `https://mcp.stack-ai.com/mcp`

{% tabs %}
{% tab title="Claude Desktop" %}
Add the following to your `claude_desktop_config.json`

```json
{
    "mcpServers": {
      "stackai": {
        "url": "https://mcp.stack-ai.com/mcp"
      }
    }
  }
```

{% endtab %}

{% tab title="Cursor" %}
Go to Settings → MCP → Add Server and enter `https://mcp.stack-ai.com/mcp`
{% endtab %}

{% tab title="MCP Inspector" %}
Run&#x20;

```bash
npx @modelcontextprotocol/inspector https://mcp.stack-ai.com/mcp
```

{% endtab %}
{% endtabs %}

#### Option 2: Self-Hosted via Prefect Horizon

After deploying on <https://horizon.prefect.io>, your server is live at: `https://<your-server-name>.fastmcp.app/mcp`

Use that URL in place of the hosted URL above. Everything else — client config, auth flow — is identical.

{% tabs %}
{% tab title="Claude Desktop" %}
Add the following to your `claude_desktop_config.json`

```json
{
    "mcpServers": {
      "stackai": {
        "url": "https://<your-server-name>.fastmcp.app/mcp"
      }
    }
  }
```

{% endtab %}

{% tab title="Cursor" %}
Go to Settings → MCP → Add Server and enter `https://<your-server-name>.fastmcp.app/mcp`
{% endtab %}

{% tab title="MCP Inspector" %}
Run&#x20;

```bash
npx @modelcontextprotocol/inspector https://<your-server-name>.fastmcp.app/mcp
```

{% endtab %}
{% endtabs %}

#### Option 3: Self-Hosted via Docker

After deploying your Docker container and pointing a domain to it, your MCP endpoint will be: `https://<your-domain>/mcp`

{% tabs %}
{% tab title="Claude Desktop" %}
Add the following to your `claude_desktop_config.json`

```json
{
    "mcpServers": {
      "stackai": {
        "url": "https://<your-domain>/mcp"
      }
    }
  }
```

{% endtab %}

{% tab title="Cursor" %}
Go to Settings → MCP → Add Server and enter `https://<your-domain>/mcp`
{% endtab %}

{% tab title="MCP Inspector" %}
Run&#x20;

```bash
npx @modelcontextprotocol/inspector https://<your-domain>/mcp
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Note on Self-Hosting**&#x20;

Your server must be accessible over HTTPS with a valid certificate.&#x20;

Plain http\:// or self-signed certificates will be rejected by most MCP clients. Make sure SERVER\_BASE\_URL in your environment config matches the public domain exactly. A mismatch will break the OAuth login callback.
{% endhint %}

#### Verify the Connection

You can confirm the server is reachable before connecting your client:

```shellscript
curl https://mcp.stack-ai.com/healthz
# Expected: {"status": "healthy"}
```

Once connected, ask the AI assistant to run `whoami`. It should return your Stack AI account email.

#### First-Time Login

Regardless of which option you use, the first connection triggers an OAuth login:

&#x20; 1\. Your MCP client opens a browser window

&#x20; 2\. Sign in with your Stack AI credentials

&#x20; 3\. Authorize the client when prompted

&#x20; 4\. The browser redirects back and your client is connected

After this, your session is stored by the client and you won't need to log in again unless your token expires.

### Example Usage

#### Run a Workflow

Running a workflow requires three input parameters:

* `org_id`: your organization ID
* `flow_id`: the workflow ID
* `inputs`: the data to pass in (e.g. a text prompt, a file URL, an image URL)

The AI assistant can also discover these automatically by calling `list_projects` first, then passing the right values to `run_workflow`. You can optionally mention a published version to run in your prompt, or always use the latest published version by default.

#### Create a Workflow

You can ask the AI to build a workflow for you in plain language: *"Create* *a* *workflow* *that* *takes* *a* *user* *question* *and* *answers* *it* *using* *a* *PDF* *document."* The server passes your description to a Stack AI AI assistant, which automatically generates the workflow nodes and connections, saves it as a draft, and publishes it.

#### Outputs

When a workflow runs, you will receive the workflow's result and a verbose option if you want the full raw output instead of a simplified summary.