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

# Builds

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

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

## Build Configuration

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

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

### 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.

```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.

```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

## Python Project Setup

Alpic uses [uv](https://docs.astral.sh/uv/) as the default Python package manager. By default, Alpic expects your Python project to use a **uv project** structure with a `pyproject.toml` file. If your project follows this convention, no additional configuration is needed — Alpic will automatically detect and install your dependencies.

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

If your project uses a simple `main.py` file with a `requirements.txt` for dependencies, you need to override the install command either 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, so you don't need to override `startCommand`.

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

## Troubleshooting

### Build Fails: "No MCP transport found"

If Alpic cannot detect a transport type, the build will fail. To resolve:

1. Create an `xmcp.config.ts` file with your transport type
2. Ensure you're importing from the correct MCP SDK path (TypeScript)
3. Add an explicit transport parameter to `mcp.run()` (Python)

<Warning>
  Make sure your project uses one of the supported MCP frameworks. Alpic automatically detects transport for projects
  using the official MCP SDKs.
</Warning>