multica-ai/multica · error

add workspace mcp server: %w

Error message

add workspace mcp server: %w

What it means

Wrapped failure of the HTTP POST to /api/workspaces/{id}/mcp-servers performed by `multica workspace mcp add`. The chained cause is typically a 400 for malformed/invalid config JSON, 409 for a duplicate server name, 404 for an unknown workspace, or auth/network errors.

Source

Thrown at server/cmd/multica/cmd_workspace.go:662

	if err != nil {
		return err
	}
	if !ok {
		return fmt.Errorf("one of --server-config, --server-config-stdin, or --server-config-file is required")
	}

	client, err := newAPIClient(cmd)
	if err != nil {
		return err
	}

	ctx, cancel := cli.APIContext(context.Background())
	defer cancel()

	var server workspaceMcpServer
	body := map[string]any{"name": serverName, "config": entry}
	if err := client.PostJSON(ctx, "/api/workspaces/"+wsID+"/mcp-servers", body, &server); err != nil {
		return fmt.Errorf("add workspace mcp server: %w", err)
	}

	return printWorkspaceMcpServers(cmd, []workspaceMcpServer{server})
}

func runWorkspaceMcpUpdate(cmd *cobra.Command, args []string) error {
	serverID := strings.TrimSpace(args[0])
	if serverID == "" {
		return fmt.Errorf("server ID must not be empty")
	}
	wsID, err := resolveWorkspaceArg(cmd, args[1:])
	if err != nil {
		return err
	}
	if wsID == "" {
		return fmt.Errorf("workspace ID is required: pass an id/slug/prefix as argument or set MULTICA_WORKSPACE_ID")
	}

View on GitHub (pinned to 2c0912b6ec)

Solutions

1. Read the wrapped error's HTTP status and body — 400 names the offending config field
2. For 409, either `mcp update` the existing entry or remove it first with `multica workspace mcp remove`
3. Validate the JSON locally (jq . server.json) before passing it
4. Confirm the workspace id and token permissions with `multica workspace mcp list <ws>`

Example fix

# before
multica workspace mcp add files acme --server-config '{"transport":"stdio"}'
# add workspace mcp server: 400 command is required

# after
multica workspace mcp add files acme --server-config '{"transport":"stdio","command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","/data"]}'

if !json.Valid(rawConfig) {
    return errors.New("server config is not valid JSON")
}
var probe map[string]any
if err := json.Unmarshal(rawConfig, &probe); err != nil || len(probe) == 0 {
    return errors.New("server config must be a non-empty JSON object")
}

func isValidServerConfig(v any) bool {
    m, ok := v.(map[string]any)
    if !ok {
        return false
    }
    switch m["transport"] {
    case "stdio":
        _, hasCmd := m["command"]
        return hasCmd
    case "sse", "streamable":
        _, hasURL := m["url"]
        return hasURL
    }
    return false
}

if err := client.PostJSON(ctx, path, body, &server); err != nil {
    var httpErr *apiclient.HTTPError
    if errors.As(err, &httpErr) && httpErr.StatusCode == 409 {
        // server name exists: route the caller to update instead
        return fmt.Errorf("already registered; use `multica workspace mcp update`: %w", err)
    }
    return fmt.Errorf("add workspace mcp server: %w", err)
}

When it happens

Trigger: Registering a server whose config JSON fails server-side schema validation; re-adding a server name that already exists on the workspace; posting to a workspace the token cannot write; server unreachable.

Common situations: Config object missing required keys for its transport type (e.g. no `command` for stdio, no `url` for sse/streamable); duplicate registration attempts in setup scripts; secrets inline in config that the server rejects; wrong workspace slug.

Related errors

• list workspace mcp servers: %w
• update workspace mcp server: %w
• remove workspace mcp server: %w
• %s must be a JSON object, or 'null' to clear
• list agent mcp servers: %w

AI-assisted analysis of multica-ai/multica@2c0912b6ec (2026-08-15). Data as JSON: /api/errors/42167ff547f63ec7. Report an issue: GitHub.