unknown MCP workflow name %q: missing method segment

Error message

unknown MCP workflow name %q: missing method segment

What it means

Thrown by parseMCPWorkflowName when the name carries the dapr.internal.mcp. prefix but splits into fewer than two dot-separated segments — i.e. a server name with no method segment. Valid names are dapr.internal.mcp.<server>.<method>[.<tool>]; a bare dapr.internal.mcp.<server> (or an empty remainder from a trailing-dot prefix) leaves parts like [<server>] with no parts[1] method.

Source

Thrown at pkg/runtime/wfengine/inprocess/mcp/v1/worker.go:185

		cursor = result.NextCursor
	}
	return nil, fmt.Errorf("MCP server returned more than %d pages of tools — refusing to truncate", maxListToolsPages)
}

// mcpWorkflowName is a parsed dapr.internal.mcp.<server>.<method>[.<tool>].
type mcpWorkflowName struct {
	method string
	tool   string // CallTool only
}

func parseMCPWorkflowName(name string) (mcpWorkflowName, error) {
	if !strings.HasPrefix(name, mcpnames.MCPWorkflowPrefix) {
		return mcpWorkflowName{}, fmt.Errorf("unknown MCP workflow name %q: expected prefix %q",
			name, mcpnames.MCPWorkflowPrefix)
	}
	parts := strings.Split(name[len(mcpnames.MCPWorkflowPrefix):], ".")
	if len(parts) < 2 {
		return mcpWorkflowName{}, fmt.Errorf("unknown MCP workflow name %q: missing method segment", name)
	}
	switch {
	case parts[1] == mcpnames.MCPMethodListTools && len(parts) == 2:
		return mcpWorkflowName{method: mcpnames.MCPMethodListTools}, nil
	case parts[1] == mcpnames.MCPMethodCallTool && len(parts) == 3:
		return mcpWorkflowName{method: mcpnames.MCPMethodCallTool, tool: parts[2]}, nil
	default:
		return mcpWorkflowName{}, fmt.Errorf("unknown MCP workflow name %q: expected method %q or %q",
			name, mcpnames.MCPMethodListTools, mcpnames.MCPMethodCallTool)
	}
}

// listToolsWorkflow: beforeListTools -> list-tools activity -> afterListTools.
func listToolsWorkflow(ctx *task.WorkflowContext, server *mcpserverapi.MCPServer, serverName string) (any, error) {
	if err := runBeforeListTools(ctx, server, serverName); err != nil {
		return nil, fmt.Errorf("beforeListTools failed: %w", err)
	}
	var result mcp.ListToolsResult

View on GitHub (pinned to 74ad417027)

Solutions

Always build names with mcpnames.MCPListToolsWorkflowName/MCPCallToolWorkflowName rather than templates
If hand-building, follow the exact shape dapr.internal.mcp.<server>.<method>[.<tool>] and assert the method is present
Reject MCPServer manifest names that are empty or contain the reserved prefix shape early, at admission
Add a unit test that every registered name parses (prefix, >=2 segments, known method)

Example fix

// before
name := fmt.Sprintf("%s%s", mcpnames.MCPWorkflowPrefix, serverName) // no method

// after
name := mcpnames.MCPListToolsWorkflowName(serverName)

Defensive patterns

Strategy: type-guard

Validate before calling

// Validate names before registering
rest := name[len(mcpnames.MCPWorkflowPrefix):]
if len(strings.Split(rest, ".")) < 2 {
    return fmt.Errorf("workflow name %q lacks a method segment", name)
}

Type guard

func hasMethodSegment(name string) bool {
    if !strings.HasPrefix(name, mcpnames.MCPWorkflowPrefix) { return false }
    return len(strings.Split(name[len(mcpnames.MCPWorkflowPrefix):], ".")) >= 2
}

Try / catch

parsed, err := parseMCPWorkflowName(name)
if err != nil {
    return nil, fmt.Errorf("registration bug: %w", err)
}

Prevention

Always append the method segment when composing names; prefer the mcpnames helpers
Validate MCPServer names are non-empty at admission
Cover name shapes in parser unit tests

When it happens

Trigger: Constructing/registering a name such as dapr.internal.mcp.myserver (no ListTools/CallTool segment); a server name containing characters that collapse the split (e.g. the name ending right after the server segment); hand-assembled names that forget the method segment.

Common situations: Custom tooling or tests building names by template without the method; refactors that moved the prefix constant to include/exclude a trailing dot; server names empty after manifest validation gaps.

Related errors

AI-assisted analysis of dapr/dapr@74ad417027 (2026-08-16). Data as JSON: /api/errors/8c50044fce662ec5. Report an issue: GitHub.