---
outline: deep
---

# DF0017: MCP Server Start Failure

::: warning Experimental
The agent-native surface is experimental and may change without a major version bump until it stabilizes.
:::

## Message

> Failed to start MCP server (`{transport}`): `{reason}`

## Cause

The MCP server failed while initializing. Common reasons:

- `@modelcontextprotocol/server` is not installed. This is a peer dependency — add it to your devtool's dependencies.
- The stdio transport threw during `connect()` (e.g. stdin/stdout is not available).
- The route-based MCP server (`cli.mcp`) could not load its transport module — usually the missing SDK peer dependency.

## Fix

- **Missing SDK**: `pnpm add @modelcontextprotocol/server` (or npm/yarn equivalent) in the package that imports `devframe/adapters/mcp` or enables `cli.mcp`.
- **Transport init failure**: check the underlying error (attached as `cause`) for specifics.

## Source

- [`packages/devframe/src/adapters/mcp/build-server.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/adapters/mcp/build-server.ts) — `createMcpServer()` throws `DF0017` when the stdio transport fails to `connect()`.
- [`packages/devframe/src/adapters/dev.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/adapters/dev.ts) — `createDevServer()` throws `DF0017` (transport `http`) when the route-based MCP server can't load its transport module.
