alibaba/nacos · error · NacosApiException

10000

10000

Error message

Required parameter 'serverSpecification' type McpServerBasicInfo is not present

What it means

Thrown by McpDetailForm.validate() when serverSpecification is empty. serverSpecification is a JSON-serialized McpServerBasicInfo string (the form stores it as String, not the typed object). This guards MCP server create/update endpoints. Maps to code 10000 (PARAMETER_MISSING), HTTP 400.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/form/mcp/admin/McpDetailForm.java:48

 */
public class McpDetailForm extends McpForm {
    
    @Serial
    private static final long serialVersionUID = 8016131725604983670L;
    
    private String serverSpecification;
    
    private String toolSpecification;
    
    private String resourceSpecification;
    
    private String endpointSpecification;
    
    @Override
    public void validate() throws NacosApiException {
        fillDefaultValue();
        if (StringUtils.isEmpty(serverSpecification)) {
            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING,
                "Required parameter 'serverSpecification' type McpServerBasicInfo is not present");
        }
    }
    
    public String getServerSpecification() {
        return serverSpecification;
    }
    
    public void setServerSpecification(String serverSpecification) {
        this.serverSpecification = serverSpecification;
    }
    
    public String getToolSpecification() {
        return toolSpecification;
    }
    
    public void setToolSpecification(String toolSpecification) {
        this.toolSpecification = toolSpecification;

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Provide serverSpecification as a JSON string conforming to McpServerBasicInfo in the form-encoded body.
2. Verify the field name is exactly `serverSpecification` and Content-Type is form-encoded.
3. Use the console or maintainer client to generate a correct payload example, then mirror it.

Example fix

// before
curl -X POST 'http://host/v3/admin/ai/mcp' -d 'mcpName=myMcp'
// after
curl -X POST 'http://host/v3/admin/ai/mcp' --data-urlencode 'serverSpecification={"name":"myMcp","protocol":"stdio"}'

if (serverSpecification == null || serverSpecification.isEmpty()) {
    throw new IllegalArgumentException("serverSpecification (McpServerBasicInfo JSON) required");
}

static boolean hasServerSpec(String json) {
    return json != null && !json.isEmpty();
}

catch (NacosApiException e) {
    if (e.getErrCode() == 10000 && e.getMessage().contains("serverSpecification")) { /* add JSON */ }
}

When it happens

Trigger: Calling POST /v3/admin/ai/mcp (create) or PUT (update) without the serverSpecification field, or with an empty string. The form also has optional toolSpecification/resourceSpecification/endpointSpecification JSON strings.

Common situations: Client sends only toolSpecification but forgets the mandatory server block; JSON body used instead of form params so the field is unbound; a copy-paste from an older API that named the field differently.

Related errors

• 10000
• 10000
• 20002
• 20002
• 10000

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/022286bd8fa084bc. Report an issue: GitHub.