DF0017: MCP Server Start Failure

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/sdk 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/sdk (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 — createMcpServer() throws DF0017 when the stdio transport fails to connect().
• packages/devframe/src/adapters/dev.ts — createDevServer() throws DF0017 (transport http) when the route-based MCP server can't load its transport module.