Skip to main content
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

Alpic runs your project’s own build and start scripts, which for a Skybridge 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
Most Skybridge apps deploy with no configuration.

​
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.
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:

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

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

​
installCommand

Type: string Use installCommand to override the Install Command in the Project Settings dashboard.

​
startCommand

Type: string Use startCommand to override the Start Command in the Project Settings dashboard.

​
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
Skybridge apps use Streamable HTTP by default.

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

​
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 for code examples.