Skip to main content
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.
Alpic detects configuration from your project source code. Most projects work out of the box without additional configuration.

​
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 Autocomplete

To enable autocompletion, type checking, and schema validation to your alpic.json file, add the following to the top of your file: 
{
  "$schema": "https://assets.alpic.ai/alpic.json"
}

​
buildCommand

Type: string Use buildCommand to override the Build Command in the Project Settings dashboard. 
{
  "$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. 
{
  "$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. 
{
  "$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. 
{
  "$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 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: 
{
  "$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.
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.

​
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)
Make sure your project uses one of the supported MCP frameworks. Alpic automatically detects transport for projects using the official MCP SDKs.