> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alpic.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Builds

> Learn how Alpic builds and configures your MCP App or MCP server during deployment

When you deploy your MCP App or MCP server to Alpic, the platform automatically analyzes your project to detect configuration and build requirements. This ensures your app is configured correctly without any manual setup.

## Choose what you're building

<Tabs>
  <Tab title="MCP App (Skybridge)">
    Alpic runs your project's own `build` and `start` scripts, which for a [Skybridge](https://docs.skybridge.tech/get-started/introduction) app are `skybridge build` and `skybridge start`. They build your server and your views into `dist/`.

    * **Runtime:** Node 22 or 24
    * **Transport:** Streamable HTTP by default, no configuration needed
    * **Views:** served from `dist/assets` at [`/assets`](/build-deploy/assets)

    Most Skybridge apps deploy with no configuration.
  </Tab>

  <Tab title="MCP server (Node.js)">
    Alpic installs your dependencies with your package manager (npm, pnpm, yarn or bun), then runs your project's own `build` and `start` scripts. This covers servers built with the [official TypeScript MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk), [xmcp](https://xmcp.dev) and other Node.js frameworks.

    * **Runtime:** Node 22 or 24, read from `.nvmrc` or `engines.node` in `package.json`
    * **Transport:** detected from your SDK imports or `xmcp.config.ts` (see [Transport Sourcing](#transport-sourcing-during-deployment))
    * **Output directory:** `dist` by default
  </Tab>

  <Tab title="MCP server (Python)">
    Alpic uses [uv](https://docs.astral.sh/uv/) as the default Python package manager. It expects a **uv project** with a `pyproject.toml` file, installs with `uv sync` and starts with `uv run main.py`. This covers servers built with [FastMCP](https://gofastmcp.com) and the [official Python MCP SDK](https://github.com/modelcontextprotocol/python-sdk).

    * **Runtime:** Python 3.13 or 3.14, read from `.python-version` or `requires-python` in `pyproject.toml`
    * **Transport:** detected from your `mcp.run()` or `mcp.http_app()` call (see [Transport Sourcing](#transport-sourcing-during-deployment))

    **Using `requirements.txt` instead of `pyproject.toml`**

    If your project uses a `main.py` file with a `requirements.txt`, override the install command in your **Project Settings** or in your `alpic.json`:

    ```json theme={null}
    {
      "$schema": "https://assets.alpic.ai/alpic.json",
      "installCommand": "uv venv && uv pip install -r requirements.txt"
    }
    ```

    The default start command (`uv run main.py`) works as-is.

    <Tip>
      We recommend migrating to a `pyproject.toml`-based uv project. You can initialize one by running `uv init` in your
      project directory.
    </Tip>
  </Tab>
</Tabs>

## Build Configuration

Alpic automatically detects your MCP framework, build commands, and transport type from your repository. You can customize build settings if needed.

For an MCP App, the build compiles both the server and its views.

<Info>
  Alpic detects configuration from your project source code. Most projects work out of the box without additional
  configuration.
</Info>

### Configuration hierarchy

1. **alpic.json**: Branch-specific configuration located in your project's repository root directory.
2. **Project settings**: Set in the Alpic UI and applied to all environments.
3. **Default configuration**: Automatically detected by Alpic.

### Configuring projects with alpic.json

This file should be created in your project's root directory and allows you to set:

* [`$schema`](#schema-autocomplete)
* [`buildCommand`](#buildcommand)
* [`buildOutputDir`](#buildoutputdir)
* [`installCommand`](#installcommand)
* [`startCommand`](#startcommand)

#### Schema Autocomplete

To enable autocompletion, type checking, and schema validation to your alpic.json file, add the following to the top of your file:

```json theme={null}
{
  "$schema": "https://assets.alpic.ai/alpic.json"
}
```

#### buildCommand

**Type**: `string`

Use `buildCommand` to override the **Build Command** in the Project Settings dashboard.

If you override the build command for an MCP App, make sure it still builds your views. Otherwise the app deploys, but its views won't load.

```json theme={null}
{
  "$schema": "https://assets.alpic.ai/alpic.json",
  "buildCommand": "npm run build"
}
```

#### buildOutputDir

**Type**: `string`

Use `buildOutputDir` to override the **Output Directory** in the Project Settings dashboard.

For an MCP App, your built views must be in an `assets` folder inside this directory, for example `dist/assets`. Alpic serves them at [`/assets`](/build-deploy/assets).

```json theme={null}
{
  "$schema": "https://assets.alpic.ai/alpic.json",
  "buildOutputDir": "server/dist"
}
```

#### installCommand

**Type**: `string`

Use `installCommand` to override the **Install Command** in the Project Settings dashboard.

```json theme={null}
{
  "$schema": "https://assets.alpic.ai/alpic.json",
  "installCommand": "npm ci"
}
```

#### startCommand

**Type**: `string`

Use `startCommand` to override the **Start Command** in the Project Settings dashboard.

```json theme={null}
{
  "$schema": "https://assets.alpic.ai/alpic.json",
  "startCommand": "npm run --silent start"
}
```

## Transport Sourcing During Deployment

Alpic automatically detects which transport type your MCP server uses by analyzing your project source code. Detection follows a priority order, using the first match found:

### xmcp.config.ts configuration file (highest priority)

If `xmcp.config.ts` exists:

* `http:` → streamablehttp
* `stdio:` → stdio

### TypeScript imports

Searches for imports from `@modelcontextprotocol/sdk/server/`:

* `stdio` → stdio
* `sse` → sse
* `streamableHttp` → streamablehttp

### Python mcp.run() or mcp.http\_app() calls

Searches for explicit transport parameters:

* `transport="stdio"` → stdio
* `transport="sse"` → sse
* `transport="streamable-http"` → streamable-http
* `transport="http"` → http

### Python mcp.run() fallback (lowest priority)

If `mcp.run()` is found without an explicit transport → defaults to stdio

<Info>Skybridge apps use Streamable HTTP by default.</Info>

## Troubleshooting

### Wrong transport detected

If Alpic can't detect your transport, it uses Streamable HTTP. If your server uses stdio or SSE, set it explicitly in `alpic.json`:

```json theme={null}
{
  "$schema": "https://assets.alpic.ai/alpic.json",
  "transportType": "stdio"
}
```

### Views don't load after deploy

Your MCP App deploys, but its views stay blank in ChatGPT or Claude. Alpic serves views from the `assets` folder inside your build output directory (`dist/assets` by default). Check that:

* your build command builds your views as well as your server
* the built views end up in `<buildOutputDir>/assets`

### Wrong runtime version

Alpic reads your Node version from `.nvmrc` or `engines.node` in `package.json`, and your Python version from `.python-version` or `requires-python` in `pyproject.toml`. Supported runtimes are Node 22 and 24 and Python 3.13 and 3.14. If none of these files exist, the dashboard preselects Node 24, so add one of them, or pick the runtime yourself when you create the project.

### Deployment fails with "Server returned status 404 on /mcp"

After the build, Alpic checks that your server answers on `/mcp` (or `/sse` for SSE), trying 3 times. If your server listens on another path, move your MCP handler to `/mcp`. See [Troubleshooting](/troubleshooting#deployment-fails-with-404-on-/mcp) for code examples.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.